Claude-Obsidian-Connector

An MCP (Model Context Protocol) server that gives Claude direct access to your local Obsidian vault. Claude can search your notes and retrieve only the sections it needs — without loading your entire vault into context.

---

Features

• Fast search — BM25 full-text search indexes your vault on startup, no ML models or internet required
• Precise retrieval — notes are split by headers so Claude gets only the relevant section, not the whole file
• Works on macOS, Windows, and Linux
• 3 tools available to Claude:
  • search_vault — search for notes matching a query
  • read_note — read the full content of a specific note
  • list_notes — list all notes in the vault or a subfolder

---

Requirements

• Python 3.10+
• Claude Code CLI

---

Installation

Step 1 — Install the package

pip install git+https://github.com/LaGrandma/Claude-Obsidian-Connector.git

Step 2 — Find your vault path

Open Obsidian → Settings → About → Vault path

Step 3 — Register the MCP server

Run the command for your operating system, replacing the path with your actual vault path.

macOS / Linux

claude mcp add obsidian -s user -e OBSIDIAN_VAULT_PATH=/path/to/your/vault -- obsidian-mcp

Windows (Command Prompt)

claude mcp add obsidian -s user -e OBSIDIAN_VAULT_PATH=C:\path\to\your\vault -- obsidian-mcp

Windows (PowerShell)

claude mcp add obsidian -s user -e OBSIDIAN_VAULT_PATH="C:\path\to\your\vault" -- obsidian-mcp

The -s user flag makes it available globally across all your projects.

Step 4 — Verify it's connected

claude mcp list

You should see obsidian: ✓ Connected.

---

Usage

Once installed, just ask Claude naturally in any Claude Code session:

Search my notes about the French Revolution

What do my notes say about mitosis?

List all my notes in the Class Notes folder

Read my note on Extended Essay ideas

Claude will automatically call the right tool and return only what's relevant.

---

Token safety

Four independent layers prevent runaway token usage:

Layer	What it does	Default	Env var to change
Per-call output cap	Max chars returned per search result chunk	800 chars	—
Per-call result cap	Max results search_vault can return	10 results	—
Per-call note cap	Max chars read_note returns	12,000 chars	—
Session budget	Max total chars returned across all calls in a session	100,000 chars	OBSIDIAN_SESSION_BUDGET
Rate limit	Max tool calls per minute	30/min	OBSIDIAN_RATE_LIMIT
Query limit	Max length of a search query	500 chars	—

Once the session budget is hit, all further calls are blocked until you start a new Claude Code session.

To increase or decrease the session budget or rate limit, add the env vars when registering:

macOS / Linux

claude mcp add obsidian -s user \
  -e OBSIDIAN_VAULT_PATH=/path/to/vault \
  -e OBSIDIAN_SESSION_BUDGET=50000 \
  -e OBSIDIAN_RATE_LIMIT=20 \
  -- obsidian-mcp

---

Keeping notes private

Add #HIDE anywhere in a note to exclude it from Claude's index. Claude will never see or retrieve that note.

#HIDE

# My Private Journal
...

You can use a different tag by setting OBSIDIAN_PRIVATE_TAG when registering the server:

macOS / Linux

claude mcp add obsidian -s user \
  -e OBSIDIAN_VAULT_PATH=/path/to/vault \
  -e OBSIDIAN_PRIVATE_TAG=#SECRET \
  -- obsidian-mcp

Windows (PowerShell)

claude mcp add obsidian -s user -e OBSIDIAN_VAULT_PATH="C:\path\to\vault" -e OBSIDIAN_PRIVATE_TAG="#SECRET" -- obsidian-mcp

---

How it works

On startup, the server walks your vault and indexes every note. Notes are chunked by markdown headers (#, ##, ###) so that when Claude searches, it receives the specific section that matches — not the entire file. This keeps responses fast and focused.

---

Uninstall

claude mcp remove obsidian
pip uninstall claude-obsidian-connector

---

Troubleshooting

obsidian-mcp: command not found The install location isn't on your PATH. Find where pip installs scripts and add it:

• macOS/Linux: ~/.local/bin or the output of python3 -m site --user-base + /bin
• Windows: %APPDATA%\Python\Scripts

Then re-run the claude mcp add command.

No MCP servers configured Make sure you used the -s user flag so the server is registered globally, not just for one project.

---

Contributing

Pull requests welcome. If you run into issues, open a GitHub issue with your OS, Python version, and vault structure.