obsidian-mcp

MCP server exposing an Obsidian vault to LLM clients (Claude, Cursor, Continue, ...).

Why?

A Second Brain should be queryable by AI agents — without shipping your data to a third-party API. This server gives any MCP-compatible client read and write access to a local Obsidian vault via the Model Context Protocol.

Key differentiators (vs. existing Obsidian MCP servers):

• Headless & filesystem-native — no Obsidian desktop app required, container-ready

• Structured output schemas on every tool — LLMs know exactly what to expect

• Vault graph analytics — wikilink graph, orphan detection, outlink tracing

• Vault health check — automated quality scoring (broken links, untagged, TODOs, duplicates)

• Policy enforcement — write log, raw/ immutability, agent locking, and wiki-index upkeep enforced at the filesystem choke point, not left to client discipline

• Ranked full-text search — Whoosh-backed index with Lucene-style query syntax (fields, booleans, phrases, wildcards, fuzzy, ranges, did-you-mean)

• AI-optimized tool descriptions — 5-element docstring pattern with actionable error messages

Related MCP server: obsidian-tools

Features

• Read and Search notes (full-text, case-insensitive)

• Create, Update, Delete notes with proper YAML frontmatter

• Append to notes (upsert), patch sections under headings

• Frontmatter and tag management (get/set/delete, dedup, case-insensitive)

• Daily notes (YYYY-MM-DD format with date validation)

• Search & replace (literal + regex with capture groups)

• Backlink graph traversal (wikilinks)

• Vault structure as a JSON resource

• Path traversal protection on all entry points (vault sandbox)

• Tag extraction (frontmatter + inline tags)

• Structured output schemas for every MCP tool (22/22)

• Vault write policies: write log (.vault-write-log.jsonl), raw/ immutability, agent lock (.vault-lock), wiki/index.json upkeep, link checking

• archive_note: archive-instead-of-delete with backlink reporting

• Incremental Whoosh full-text index (BM25, stemmed, field queries, fuzzy, did-you-mean) with configurable index directory

• Vault graph analytics (nodes, edges, stats, broken links)

• Vault health scoring (0–100 with actionable issue report)

Documentation

Quick Start

pip install -e .

# Point at your real vault
export OBSIDIAN_VAULT_ROOT=/path/to/your/obsidian/vault

# Run (stdio transport)
obsidian-mcp

Or use the bundled mock vault (no config needed):

obsidian-mcp   # uses examples/mock-vault/

Client Integration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp",
      "env": {
        "OBSIDIAN_VAULT_ROOT": "/path/to/your/vault"
      }
    }
  }
}

Cursor

Cursor supports MCP from version 0.42+. Configure in ~/.cursor/mcp.json (same format as Claude Desktop).

Any other MCP client

The server runs on stdio. Register it with your client's standard MCP configuration (command: obsidian-mcp or python3 -m obsidian_mcp.server, env: OBSIDIAN_VAULT_ROOT).

Tools (22)

Prompts (3)

Resources (1)

Architecture

MCP Client  ←—MCP stdio—→  obsidian-mcp server  →  vault.py  →  Obsidian Vault
(Claude/Cursor/...)         (22 tools + 3 prompts)   (filesystem)   (*.md + YAML)
                            + 1 resource                 │
                                        policies.py ←——————┘ (write log, raw lock,
                                                        wiki index, link check)
                                        search_index.py → Whoosh index (BM25)

Design decisions:

• Filesystem-native instead of REST API: headless, containerizable, no app dependency

• Path traversal protection at all entry points (_resolve(), _resolve_folder())

• Singleton pattern for Vault instance (testable via set_vault())

• Pydantic BaseModel return types for outputSchema on all 22 tools

Development

pip install -e ".[dev]"
pytest tests/       # 167 tests, all passing

CI runs on Python 3.10, 3.11, and 3.12 with pytest + ruff.

License

MIT