Obsidian Brain — Claude Code MCP server for vault search and edits
A local MCP server that hands your agent semantic search, a link graph and write access to an Obsidian vault. It works on plain .md files on disk.
claude mcp add --env VAULT_PATH=<VAULT_PATH> --env DATA_DIR=<DATA_DIR> --env EMBEDDING_PRESET=<EMBEDDING_PRESET> --env EMBEDDING_MODEL=<EMBEDDING_MODEL> --env EMBEDDING_PROVIDER=<EMBEDDING_PROVIDER> --transport stdio obsidian-brain -- npx -y obsidian-brainWhat Obsidian Brain does
Obsidian Brain reads the vault straight from the filesystem, so Obsidian can stay closed. A single Node process splits notes into heading-aware chunks and keeps them in a SQLite index alongside FTS5 full-text search. The default search mode is hybrid: semantic hits are fused with BM25 through Reciprocal Rank Fusion.
The tools come in groups. Lookup: search, list_notes, read_note. Graph work: find_connections, find_path_between, detect_themes, rank_notes. Writing: create_note, edit_note, apply_edit_preview, link_notes, move_note, delete_note. Housekeeping: reindex, index_status. Edits hit the disk right away and the affected file gets re-indexed.
You need Node 20+ and a vault path in VAULT_PATH; without it the server won't start. The first boot indexes the vault and downloads an embedding model of about 34 MB, so tools take a while to show up in the client. Local embeddings can come from Ollama, with the model picked through an env var. The live-editor tools, Dataview and Bases need the separate companion plugin, and its major.minor version has to match the server's.
What it helps with
- pull the right passage out of a vault by meaning, not exact wording
- see which notes bridge two themes in your notes
- write or amend a note from inside a chat with the agent
- rename a file without breaking links pointing at it
- check what is indexed and when it was last refreshed
Example prompts for the agent
- Search the vault for everything I wrote about indexing and show the closest chunks by meaning
- Which notes connect my MCP notes with my Obsidian notes? Trace a path between them
- Create a note for this week's plan and link it from
inbox.md
How to install Obsidian Brain
Platform CLI
claude mcp add --env VAULT_PATH=<VAULT_PATH> --env DATA_DIR=<DATA_DIR> --env EMBEDDING_PRESET=<EMBEDDING_PRESET> --env EMBEDDING_MODEL=<EMBEDDING_MODEL> --env EMBEDDING_PROVIDER=<EMBEDDING_PROVIDER> --transport stdio obsidian-brain -- npx -y obsidian-brainReplace <…> with your own values. 14 more environment variables are in the server README
Platform CLI
codex mcp add obsidian-brain --env VAULT_PATH=<VAULT_PATH> --env DATA_DIR=<DATA_DIR> --env EMBEDDING_PRESET=<EMBEDDING_PRESET> --env EMBEDDING_MODEL=<EMBEDDING_MODEL> --env EMBEDDING_PROVIDER=<EMBEDDING_PROVIDER> -- npx -y obsidian-brainReplace <…> with your own values. 14 more environment variables are in the server README
Config file
{
"mcpServers": {
"obsidian-brain": {
"command": "npx",
"args": [
"-y",
"obsidian-brain"
],
"env": {
"VAULT_PATH": "<VAULT_PATH>",
"DATA_DIR": "<DATA_DIR>",
"EMBEDDING_PRESET": "<EMBEDDING_PRESET>",
"EMBEDDING_MODEL": "<EMBEDDING_MODEL>",
"EMBEDDING_PROVIDER": "<EMBEDDING_PROVIDER>"
}
}
}
}Replace <…> with your own values. 14 more environment variables are in the server README
Config file
{
"servers": {
"obsidian-brain": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"obsidian-brain"
],
"env": {
"VAULT_PATH": "<VAULT_PATH>",
"DATA_DIR": "<DATA_DIR>",
"EMBEDDING_PRESET": "<EMBEDDING_PRESET>",
"EMBEDDING_MODEL": "<EMBEDDING_MODEL>",
"EMBEDDING_PROVIDER": "<EMBEDDING_PROVIDER>"
}
}
}
}Replace <…> with your own values. 14 more environment variables are in the server README
Platform CLI
gemini mcp add -e VAULT_PATH=<VAULT_PATH> -e DATA_DIR=<DATA_DIR> -e EMBEDDING_PRESET=<EMBEDDING_PRESET> -e EMBEDDING_MODEL=<EMBEDDING_MODEL> -e EMBEDDING_PROVIDER=<EMBEDDING_PROVIDER> obsidian-brain npx -y obsidian-brainReplace <…> with your own values. 14 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Obsidian Brain
How do I install Obsidian Brain in Claude Code?
Run claude mcp add obsidian-brain -e VAULT_PATH=<VAULT_PATH> -- npx -y obsidian-brain, replacing <VAULT_PATH> with the absolute path to your vault.
What does Obsidian Brain do?
It exposes an Obsidian vault to an MCP client: chunk-level search, graph traversal, note reading and writing. Obsidian itself does not need to be running.
Do I need a plugin inside Obsidian?
Not for the core tools. active_note, dataview_query and base_query only light up with the companion plugin, and its version has to line up with the server down to major.minor.
