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

Related MCP server: mcp-obsidian

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 version:

uvx cache clean

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