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

uvx cache clean

Tools

Tool	Description
read_note	Read a note with frontmatter
write_note	Create or update a note (overwrite / append / prepend)
patch_note	Edit part of a note via find-and-replace
list_directory	Browse vault folders
delete_note	Delete a note (requires path confirmation)
search_notes	Full-text BM25 search across content and/or frontmatter
move_note	Move or rename a note
move_file	Move any file with dual path confirmation
read_multiple_notes	Batch read up to 10 notes
update_frontmatter	Update YAML frontmatter without touching body
get_notes_info	File metadata without reading content
get_frontmatter	Extract frontmatter only
manage_tags	Add, remove, or list tags
get_vault_stats	Total notes, folders, size, recently modified
list_all_tags	All tags across vault with occurrence counts

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