Brain MCP

What brain-mcp MCP server does

The brain-mcp MCP server exposes an Obsidian vault as persistent context for MCP-compatible AI clients. Notes remain as Markdown files in a folder controlled by the user, while the server maintains a SQLite index containing full-text search data, section embeddings, links, topics, and project metadata.

It supports both reading and writing. Agents can load identity and project context, search notes, inspect individual sections, follow links, review recent changes, capture new notes, remember facts, edit existing content, move notes, or send notes to .trash/ instead of permanently deleting them.

How it works

A file watcher updates the index after vault changes. Notes are divided into sections, with links, topics, and project information extracted for retrieval and graph operations. Embeddings use the bge-small-en-v1.5 model, and candidate results can be reranked with bge-reranker-base. These models run locally on the CPU and are downloaded into data/models.

Queries are expanded for known shorthand and corrected against words found in the vault. Retrieval combines BM25 keyword matches, semantic similarity, exact dates, and note-title matches. Reciprocal rank fusion combines those result sets before reranking selected candidates. If the strongest passage is below the configured relevance floor, the server reports that the vault does not contain a relevant answer rather than presenting a weak match.

The server can communicate over stdio, HTTP with a bearer token, or OAuth 2.1 with PKCE through Cloudflare Tunnel. Notes do not leave the server during normal local operation. Remote access includes scopes, secret redaction, and an audit log of calls.

Setup and configuration

The repository targets Node.js 22 or newer and uses strict TypeScript. The provided material describes a local Obsidian vault as the source of truth and a single Node process with one SQLite file as the main architecture.

Hybrid retrieval is enabled by default according to the documentation. Set BRAIN_MCP_HYBRID=0 to use keyword-only retrieval. Retrieval behavior can also be adjusted in brain.config.json, including embedding and reranker models, candidate counts, score blending, the relevance floor, shorthand expansions, and context budgets. Additional constants such as RRF_K and TITLE_BONUS are available in the indexing code.

Tools and capabilities

• brain_identity returns profile, memory, facts, skills, projects, and recent focus; it accepts an optional topic.
• brain_context selects relevant sections under a size budget and reports source notes and coverage.
• brain_search returns ranked note snippets with project, type, topic, and date filters.
• brain_read, brain_project, brain_graph, and brain_recent inspect notes, projects, links, backlinks, shared topics, and recent changes.
• brain_capture, brain_remember, brain_write, brain_edit, brain_move, and brain_delete provide constrained write operations.

brain_remember rejects near-duplicate facts unless forced, can mark partial overlaps with a supersession line, and feeds captured facts into identity results. Writes are limited to allowed folders, with Notes/ and the capture folder writable by default. Moving does not overwrite existing notes and reports links that no longer resolve; deletion moves content to .trash/.

Limitations and notes

The brain-mcp MCP server depends on the structure and content of the connected vault. It can explicitly report missing coverage, but it cannot supply information that the notes do not contain. The hybrid models are local and retrieval falls back to keywords while they are unavailable. The current design uses fixed retrieval rules, one process, and one SQLite database; the documentation identifies pluggable retrievers, storage, and graph strategies as future possibilities rather than current features.