A Python MCP (Model Context Protocol) server giving an LLM client (e.g. Claude Desktop) read/write access to local Obsidian vaults, via direct filesystem access — no Obsidian Local REST API plugin, no HTTP, no auth token required.
This is a Python port of obsidian-mcp (TypeScript), functionally equivalent with a few deliberate fixes and simplifications — see Plans/review-the-typescript-obsidian-mcp-parsed-shamir.md and ISA.md for the full rationale.
Warning: This server has read/write access to your vault. Back up your notes (e.g. via git) before use.
- Python 3.11+
uv- An Obsidian vault (a directory that has been opened by Obsidian at least once, i.e. contains a
.obsidian/app.json) - macOS or Linux (Windows is not supported — see ISA "Out of Scope")
The PyPI distribution is named py-obsidian-mcp (the obsidian-mcp name was already taken by an unrelated project) — the installed command is still obsidian-mcp.
uvx --from py-obsidian-mcp obsidian-mcp /path/to/your/vault [/path/to/another/vault ...]
# or: pip install py-obsidian-mcp && obsidian-mcp /path/to/your/vaultuv sync
uv run obsidian-mcp /path/to/your/vault [/path/to/another/vault ...]Vault names are auto-derived from each directory's basename (lowercased, non-alphanumeric characters become hyphens, duplicates get a numeric suffix). Up to 10 vaults; vault paths must not be nested inside one another.
Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"obsidian": {
"command": "uvx",
"args": ["--from", "py-obsidian-mcp", "obsidian-mcp", "/path/to/your/vault"]
}
}
}Or, running from a local clone instead of the published package:
{
"mcpServers": {
"obsidian": {
"command": "uv",
"args": ["run", "--directory", "/path/to/py-obsidian-mcp", "obsidian-mcp", "/path/to/your/vault"]
}
}
}read-note, create-note, edit-note (append/prepend/replace/delete), delete-note (soft-delete to .trash/ by default), move-note, create-directory, search-vault (content/filename/tag search, with an optional max_results), add-tags, remove-tags, rename-tag (vault-wide, hierarchy-preserving), list-available-vaults.
Also exposes an obsidian-vault:// resource scheme (vault listing/info) and a list-vaults prompt.
uv sync --all-extras
uv run pytest -q
uv run ruff check src tests- Every tool validates that target paths stay within the vault (
src/obsidian_mcp/utils/path_safety.py), including symlink-aware containment checks. - The TypeScript original had a confirmed bug where this containment check was effectively a no-op (an async validation function was called without
await). This port's path-safety functions are all synchronous, structurally preventing that class of bug.