笔记库访问 MCP 服务器

obsidian-mcp

Python MCP server for Obsidian vault access. A port of bitbonsai/mcpvault using uv Python instead of Node.js — designed for local use across multiple vaults.

Features

• 15 tools covering all vault operations: read, write, patch, search, move, delete, tag management, frontmatter, and vault stats
• BM25 full-text search with multi-word relevance reranking
• Safe frontmatter — YAML parsed with yaml.safe_load, key order preserved on writes
• Security hardened — path traversal prevention with lexical + symlink boundary checks (mirrors mcpvault v0.9.1), PathFilter blocks .obsidian/, .git/, and non-note extensions, destructive ops require path confirmation
• Multi-vault — run one instance per vault, each with its own MCP server name
• Pure Python — no Node.js required, managed entirely by uv

Requirements

• macOS (tested) or Linux
• uv — Python package manager (brew install uv)
• Python 3.11+ (installed automatically by uv)
• Claude Desktop or Claude Code

Quick Start (no clone required)

Install uv, then point your MCP client config at the GitHub repo directly — uvx handles the rest.

brew install uv

Claude Code

claude mcp add --scope user obsidian-my-vault \
  uvx -- \
  --from git+https://github.com/Sub-Lime-Time/mcp-obsidian \
  obsidian-mcp "/path/to/your/vault" obsidian-my-vault

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json

Note: Claude Desktop's "Add custom connector" UI (Settings → Connectors) only supports remote HTTP/SSE servers. Local stdio servers like this one require JSON config editing.

Claude Desktop doesn't inherit your shell PATH, so use the full path to uvx (find it with which uvx):

{
  "mcpServers": {
    "obsidian-my-vault": {
      "command": "/opt/homebrew/bin/uvx",
      "args": [
        "--from", "git+https://github.com/Sub-Lime-Time/mcp-obsidian",
        "obsidian-mcp",
        "/path/to/your/vault",
        "obsidian-my-vault"
      ]
    }
  }
}

Common uvx paths: /opt/homebrew/bin/uvx (macOS Apple Silicon), /usr/local/bin/uvx (macOS Intel), ~/.local/bin/uvx (Linux).

iCloud Vault Path (macOS)

/Users/<username>/Library/Mobile Documents/iCloud~md~obsidian/Documents/<Vault Name>

Multiple vaults

Run one instance per vault, each with a unique server name:

claude mcp add --scope user obsidian-work \
  uvx -- \
  --from git+https://github.com/Sub-Lime-Time/mcp-obsidian \
  obsidian-mcp "/path/to/work/vault" obsidian-work

Updating

uvx caches the installed package. To pull the latest main and confirm which commit you're on:

uvx --refresh --from git+https://github.com/Sub-Lime-Time/mcp-obsidian python -c "import json, importlib.metadata as m; print('mcp-obsidian at', json.loads(m.distribution('obsidian-mcp').read_text('direct_url.json'))['vcs_info']['commit_id'][:7])"

Compare the printed commit with the latest one on main, then restart your MCP client so the server process picks up the new code. In Claude Desktop, quit with ⌘Q and reopen. In Claude Code, start a new session or reconnect the server in /mcp.

This works while the server is running, so an AI assistant can run it for you. Don't use uv cache clean for updates: a running uvx server holds uv's cache lock, so the clean waits and then fails after UV_LOCK_TIMEOUT (300 s by default) unless every client using the server is closed first. (uvx cache clean doesn't work either; it tries to run a tool named cache.)

Tools

Development

# Clone and install
git clone https://github.com/Sub-Lime-Time/mcp-obsidian.git
cd mcp-obsidian
uv sync

# Verify
uv run obsidian-mcp --help

# Run against a vault
uv run obsidian-mcp /path/to/vault

# Add a dependency
uv add <package>

See CLAUDE.md for architecture notes and rules for AI assistants working in this repo.

Contributing

Bug fixes and clear improvements are welcome — open a PR. For new features, please open an issue first to discuss before writing code. I'll merge fixes that are unambiguously correct, but make no guarantees on feature additions.

Credits

Based on bitbonsai/mcpvault (MIT). Security model mirrors mcpvault v0.9.1.

License

MIT