obsidian-mcp

obsidian-mcp

A Model Context Protocol server that lets any MCP-compatible AI host (Cursor, Claude Desktop, Zed, etc.) read, search, link, and write notes inside a local Markdown / Obsidian vault.

  

---

What is this?

obsidian-mcp is an MCP server. MCP is an open standard from Anthropic for connecting AI assistants to external tools and data sources — think "USB-C for AI applications". Once this server is registered with an MCP host you can ask the model questions like:

"What did I learn about MCP this week, and which of my notes link to it?"

…and the model will call this server's tools (search_notes, find_backlinks, get_recent_notes, …) to answer using your actual notes.

Status

| Phase | Scope | State | |------:|------|------| | 0 | Repo skeleton, CI, sample vault, server stub with get_note | shipped | | 1 | Sandboxed pathing, parser, reader, tests | shipped | | 2 | Search, listings, backlinks, tag index | planned | | 3 | Resources (notes as obsidian:// URIs) | planned | | 4 | Write tools (create_note, append_to_note) + atomic writes | planned | | 5 | Prompts (/weekly-review, /daily-note-template) | planned |

Architecture

┌────────────────┐    stdio JSON-RPC    ┌────────────────────────┐
│  MCP host      │ ───────────────────► │  obsidian-mcp server   │
│ (Cursor /      │                      │  (this repo)           │
│  Claude /      │                      │                        │
│  Zed)          │                      │  tools / resources /   │
└────────────────┘                      │  prompts               │
                                        └───────────┬────────────┘
                                                    │
                                        sandboxed   ▼
                                        ┌────────────────────────┐
                                        │  Local Markdown vault  │
                                        └────────────────────────┘

Every caller-supplied path is funnelled through a single sandboxing function (utils/pathing.py::safe_resolve) before any filesystem access, so the server cannot be coerced into reading files outside the configured vault root.

Quickstart

1. Install

git clone https://github.com/darrenlopez/obsidian-mcp.git
cd obsidian-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

2. Try it against the bundled sample vault

OBSIDIAN_MCP_VAULT_PATH="$(pwd)/sample-vault" \
  npx @modelcontextprotocol/inspector \
  python -m obsidian_mcp

This launches Anthropic's official MCP Inspector pointed at this server, so you can interactively call get_note and inspect schemas without leaving your browser.

3. Register with Cursor

Add the following to your Cursor MCP config (~/.cursor/mcp.json or the Cursor settings UI):

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["-m", "obsidian_mcp"],
      "env": {
        "OBSIDIAN_MCP_VAULT_PATH": "/absolute/path/to/your/vault",
        "OBSIDIAN_MCP_READ_ONLY": "false"
      }
    }
  }
}

4. Register with Claude Desktop

Add the same block to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (or the platform equivalent).

Configuration

All configuration is via environment variables (prefix OBSIDIAN_MCP_).

| Variable | Default | Purpose | |---|---|---| | OBSIDIAN_MCP_VAULT_PATH | (required) | Absolute path to the vault root. | | OBSIDIAN_MCP_READ_ONLY | false | When true, write tools are not registered. | | OBSIDIAN_MCP_MAX_FILE_KB | 1024 | Max note size (KiB) returned by read operations. | | OBSIDIAN_MCP_INCLUDE_HIDDEN | false | Include dotfiles and .obsidian/ in listings/search. |

Tools (Phase 0 / 1)

| Tool | Description | |------|-------------| | get_note(path) | Read a single note, returning parsed frontmatter, tags, and outgoing wikilinks. |

The Phase 2+ tool surface (search_notes, list_notes, find_backlinks, list_tags, get_recent_notes, …) is documented in the architecture plan and tracked in STATUS.

Security

This server reads (and, in non-read-only mode, writes) files on your machine. Some choices that limit blast radius:

• Sandboxed paths. Every path is resolved through safe_resolve(vault_root, user_input),

which rejects absolute paths, .. segments, and symlink escapes before any filesystem touch.

• Read-only mode. Set OBSIDIAN_MCP_READ_ONLY=true and write tools are

not registered at all.

• Size limits. OBSIDIAN_MCP_MAX_FILE_KB caps the bytes returned by read

operations to prevent DoS via huge files.

• Hidden-file exclusion. .obsidian/ and dotfiles are skipped by default,

so plugin secrets do not leak into model context.

• No network. The server makes no outbound network requests of its own.
• No shell=True, no eval. Anywhere.

Development

pip install -e ".[dev]"
ruff check .
ruff format --check .
mypy
pytest

The test suite includes adversarial path-traversal tests (tests/test_pathing.py) — keep them green.

License

MIT