brain-mcp
brain-mcp turns an Obsidian Markdown vault into local, searchable, writable memory for MCP-compatible AI clients.
Load the owner’s identity, preferences, projects, recent focus, and topic-specific context (
brain_identity).Answer questions from vault sections using hybrid keyword + semantic + reranker retrieval with coverage labels (
brain_context), or search notes with project/type/topic/date filters (brain_search).Read full notes or sections with metadata, topics, and links (
brain_read), get project briefings (brain_project), explore backlinks/outgoing links/shared topics (brain_graph), and list recently changed notes (brain_recent).Save durable notes (
brain_capture) and create, replace, edit, move, or delete hand-written notes inside allowed folders (brain_write,brain_edit,brain_move,brain_delete); deletes go to.trash/.Remember durable facts with categories, validity windows, replacements, duplicate checks, and query current, as-of, or historical facts (
brain_remember,brain_facts).Expose MCP resources
brain://identityandbrain://note/{path}, plus promptsassume_personaandproject_briefing.Run locally over stdio, HTTP bearer-token mode, or OAuth 2.1 remote access, with scopes, private-note protection, secret redaction, audit logging, local ONNX models with keyword fallback, file watching, imports, Docker, and retrieval evals.
Provides tools for searching, reading, writing, and managing notes in an Obsidian vault, including identity bundles, context retrieval, project briefings, graph navigation, recent notes, note capture, and memory facts. It indexes Markdown notes with frontmatter and wikilinks, and keeps the index current via a file watcher.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@brain-mcp brief me on my current projects and recent focus"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
brain-mcp
Your Obsidian vault, as memory for every AI you use.
An open-source Model Context Protocol server that serves your notes, from your own machine, to Claude and any MCP client.
Website · Quick start · How it works · Contribute · Research questions
Why brain-mcp
Every new chat starts from zero. You explain who you are, what you are building and how you like to work, and tomorrow, in another app, you explain it again.
brain-mcp keeps that context in the Markdown notes you already own. Connect any MCP client and it learns who you are, how you work, what your projects are and what you touched this week. It can search, follow links and write back to the vault as you talk.
Your files, your machine. Notes stay plain Markdown in a folder you control. Nothing is uploaded to a third party.
One memory, every client. Claude Code, Claude Desktop, claude.ai, Cursor, Hermes Agent, your phone and anything else that speaks MCP read the same vault.
Hybrid retrieval, fully local. Keyword search plus meaning search with a small embedding model, then a reranker, all on your CPU. It can also answer "the vault does not record this" instead of guessing.
Measured. Every ranking change is scored by two bundled evals, keyword and hybrid side by side.
Private by default. OAuth 2.1 with PKCE for remote access, read, write and private scopes, secret redaction and an audit log of every call.
Writes back.
brain_rememberandbrain_captureturn what a model learns into notes you can read and edit.Small and readable. About 3,800 lines of strict TypeScript. Easy to study, easy to extend.
Related MCP server: obsidian-mcp
How it works
flowchart LR
V["Obsidian vault<br/>plain Markdown"]
subgraph S["brain-mcp: one Node process, one SQLite file"]
I["Indexer<br/>sections, links,<br/>topics, projects"]
DB[("SQLite<br/>FTS5 word index<br/>section embeddings<br/>link graph")]
M["Local models on CPU<br/>bge-small embedder<br/>bge-reranker"]
R["Hybrid retrieval"]
T["14 MCP tools"]
G["Scopes, redaction,<br/>audit log"]
I --> DB --> R --> T --> G
M -.-> DB
M -.-> R
end
V -->|file watcher| I
G -->|stdio| C1["Claude Code,<br/>Claude Desktop"]
G -->|HTTP + bearer token| C2["Clients on<br/>your network"]
G -->|OAuth 2.1 through<br/>Cloudflare Tunnel| C3["claude.ai, phone,<br/>any MCP client"]
T -. "remember, capture, write,<br/>edit, move, delete<br/>(allowed folders only)" .-> VIndex. Every note is split into sections and indexed with its links, topics and project. Each section also gets an embedding (
bge-small-en-v1.5) in the background. A file watcher keeps both current within a second of a save.Retrieve. A question goes through five steps:
Understand: expand shorthands (
pg→ PostgreSQL) and fix typos against the vault's own words.Search four ways: keywords per section (BM25), meaning (embeddings), exact dates, and note titles.
Fuse the four lists with reciprocal rank fusion.
Follow links (off by default,
retrieval.graph): a section of a note linked with the top hits (hub and topic pages included, with a boost when several top hits link to the same note) can take a reranker place from the weakest fused entry it beats, and the reranker reads the sentence that links them. A section the last step would trim is kept anyway when it is linked with a kept hit.Rerank the best candidates with a cross-encoder (
bge-reranker-base), always including each list's first pick, so fusion cannot bury a hit only one search found. When keyword and meaning search agree on the top hit and fusion keeps it in the top 3, only those 3 are reranked.Decide: if even the best passage scores below the reranker's floor, answer "nothing relevant"; otherwise return the strong hits and at least the five best, cited by note, with a coverage label (good, thin, none).
Serve. Over stdio beside your editor, over HTTP with a bearer token on your network, or behind an OAuth 2.1 login through Cloudflare Tunnel for the public internet.
Remember and write.
brain_rememberappends durable facts and refuses near duplicates. A fact can replace an earlier one, expire, or start at a given date;brain_identityserves only the facts true now, andbrain_factskeeps the history. Four more tools write, edit, move and delete hand-written notes, inside the folders you allow.
The retrieval step from question to answer:
flowchart LR
Q["Question"] --> U["Understand<br/>shorthands,<br/>typo fixes"]
U --> K["Keywords<br/>per section, BM25"]
U --> D["Meaning<br/>embeddings"]
U --> DT["Exact dates"]
U --> NT["Note titles<br/>BM25"]
K & D & DT & NT --> F["Fuse<br/>reciprocal rank fusion"]
F --> RR["Rerank top 16<br/>cross-encoder<br/>(top 3 when keywords<br/>and meaning agree)"]
RR --> GT{"Best score<br/>above the floor?"}
GT -->|no| X["Nothing relevant"]
GT -->|yes| A["Cited passages<br/>coverage: good or thin"]Everything runs on your machine: the models are downloaded once into data/models, and no note leaves the server. If the models are not ready yet, retrieval falls back to keywords, so the server never blocks. Set BRAIN_MCP_HYBRID=0 to stay keyword-only.
The architecture is intentionally simple right now, and ideas are welcome. It is one process and one SQLite file, with a hybrid ranker built from fixed rules. Some of it is already tweakable: the retrieval block in brain.config.json (embedding and reranker models, how many candidates to rerank, the score blend, the "nothing relevant" floor, your own shorthands), context budgets under context, and fusion constants such as RRF_K and TITLE_BONUS in src/vault/index.ts. Much more could become configurable, such as pluggable retrievers and storage, graph strategies, and query rewriting. If you have an idea, open an issue or a research proposal, even before there is code.
Tools
Tool | What it returns |
| Persona bundle: profile note, memory notes, the captured facts that are true now, skills, project list and recent focus. The server instructions ask clients to call this first. Pass |
| The sections most relevant to a question, with source note ids and a coverage label, from the hybrid ranker, packed under a size budget. Says so explicitly when the vault does not record the answer. |
| Hybrid search (keywords, meaning, reranker, spelling correction) with project, type, topic and date filters. Returns ranked notes with snippets. |
| One note, or one section of it, with metadata, topics and resolved links. |
| Briefing on a project: description, latest progress, decisions, recent changes and notes grouped by type. With no argument it lists projects. |
| Links out, backlinks grouped by project, and notes that share topics. |
| Notes modified in the last N days, newest first. |
| Writes a new note with graph-ready frontmatter into the capture folder. Like |
| Appends a fact to the memory file; it joins |
| Captured facts and when each was true: the current ones, the ones true at an |
| Creates a note at a chosen path in a writable folder ( |
| Changes part of a note in one of three ways: replace text that matches once, replace a section under a heading, or append. Keeps the file's line endings and bumps |
| Moves or renames a note within the writable folders. Never overwrites, and names any notes whose links stop resolving. |
| Moves a note into |
The four write tools need the brain:write scope. They refuse notes a pipeline generates, hidden folders, paths outside the vault, and the memory file, which stays append-only through brain_remember.
Also exposed: the resources brain://identity and brain://note/{path}, and the prompts assume_persona and project_briefing.
The index lives in data/index.db, embeddings included. It is rebuilt on every start (about 10 ms for the 15-note example vault) and kept current by the watcher; embeddings are keyed by a hash of the text, so unchanged sections are never embedded twice. Every tool call is appended to logs/audit.jsonl.
Quick start
Requires Node 22 or newer. One command sets it up on your notes:
npx debawho-brain-mcp initIt lists the Obsidian vaults on your machine and asks which one to serve (or makes a starter vault in ~/second-brain), asks your name, offers smart search, and offers to connect Claude Code for you. Your notes stay where they are; the config, index and logs go in ~/.brain-mcp/. Then ask Claude "what do you know about me?"
The package itself is about 50 MB and searches by keyword. Smart search adds two local models that rank by meaning, and puts the right note first more often (67% against 42% on the example vault's eval). It is a one-time download of 100 to 200 MB for your platform's ONNX runtime, plus 300 MB of models, all kept in ~/.brain-mcp/. init asks for it; add it later with npx debawho-brain-mcp smart-search, or take it out with npx debawho-brain-mcp smart-search remove.
To connect a client yourself, Claude Code:
claude mcp add --scope user brain -- npx -y debawho-brain-mcp --stdiohermes mcp add brain --command npx --args -y debawho-brain-mcp --stdioClaude Desktop, Cursor and other clients that read an mcpServers config:
{
"mcpServers": {
"brain": { "command": "npx", "args": ["-y", "debawho-brain-mcp", "--stdio"] }
}
}On Windows, put cmd /c in front of npx: "command": "cmd", "args": ["/c", "npx", "-y", "debawho-brain-mcp", "--stdio"]. Run npx debawho-brain-mcp --help for the HTTP and OAuth modes.
From source
For development, the checks and evals, or Docker:
git clone https://github.com/debashishthakur/brain-mcp.git
cd brain-mcp
npm install
npm run build
node scripts/smoke.mjsThe repository ships with example-vault/, a small fictional vault belonging to Ines Varga, a backend engineer with two side projects. brain.config.json points at it, so the smoke test drives every tool, resource and prompt over stdio against real notes, then restores the vault.
The first hybrid query downloads the two models (about 300 MB) from Hugging Face into data/models. After that, everything runs offline.
Make it yours (from source)
npm run setupThe same setup as init, for a clone. It asks for your name (it suggests the one from git config) and where your notes are. Point it at an existing Obsidian vault, or press Enter for a starter vault in my-vault/ with a profile note to fill in. It writes brain.config.local.json, which git ignores and the server uses from then on, with its own index so your notes never mix with the example. It ends by printing the claude mcp add command for your machine: run it, then ask Claude "what do you know about me?"
Delete brain.config.local.json to go back to the example vault. The checks and evals always run against the example vault, so they keep passing after setup.
npm run typecheck
node scripts/verify.mjs # redaction, file watcher, HTTP bearer auth, audit log
node scripts/verify-facts.mjs # fact windows: dates, replacements, expiry, bad references
node scripts/verify-memory.mjs # brain_remember dedupe and replacements, brain_facts, identity, brain_context
node scripts/verify-write.mjs # write, edit, move and delete on a throwaway vault
node scripts/verify-oauth.mjs # the full OAuth 2.1 flow against a throwaway auth database
node scripts/verify-hybrid.mjs # hybrid search: refusal, spelling, identifiers, context
node scripts/verify-ranking.mjs # the ranker with stand-in models: empty shortlist, notes without sections, agreeOverride, the link graph
node scripts/verify-policy.mjs # notes a connection may not read never rank, appear or get named in a links line
node scripts/verify-graph.mjs # link kinds, every way of writing a link target, duplicate names, the window each link sits in
node scripts/verify-mentions.mjs # write replies name existing notes mentioned without a link, never private or already-linked ones
node scripts/verify-import.mjs # the Logseq, Notion and Markdown importers, and the links they write, read back through the server
node scripts/verify-setup.mjs # npm run setup, in a temp folder
node scripts/verify-package.mjs # the npm package as a new user gets it: pack, install, init, serve
node scripts/verify-smart-search.mjs # the smart-search add-on: this OS's runtime only, hybrid ranking, remove
node scripts/eval-retrieval.mjs # 12 questions, keyword vs hybrid
node scripts/eval-hybrid.mjs # 29 harder questions: paraphrase, typo, identifier, date, two-note, alias, off-topic
node scripts/debug-rank.mjs "your question" # trace one query: each list, the reranker shortlist and why entries were cut
node scripts/graph-stats.mjs # your link graph: links by where they sit, links written between content notes, unresolved namesIf npm install reports held-back install scripts, the two packages that need them (better-sqlite3 and esbuild) are already listed under allowScripts in package.json. Run npm install-scripts approve better-sqlite3 esbuild if your npm still asks. The scripts of onnxruntime-node and protobufjs are not needed for CPU use.
Run with Docker
Token-mode HTTP server in a container, using the example vault by default. The image is Alpine-based and searches by keyword, because the ONNX runtime behind smart search needs glibc.
export BRAIN_MCP_TOKEN="$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")"
docker compose up --buildThe compose file publishes 127.0.0.1-friendly port 3737, mounts brain.config.json and example-vault read-only, and keeps data/ and logs/ on the host. Health is checked at GET /healthz.
Keep the service private. The container binds 0.0.0.0 only so Docker can publish the port. Publish it on loopback (127.0.0.1:3737:3737) or a private network such as Tailscale — do not expose it to the public internet. Anything public should use OAuth (--oauth) behind a TLS proxy, as in the security model below.
To use your own vault, point vaultPath at a host mount (or replace the example-vault volume) and keep BRAIN_MCP_CONFIG on a config file whose vaultPath matches that mount.
Retrieval eval
Two scripts score retrieval on the example vault, keyword and hybrid side by side. Results are deterministic and reproducible from a fresh clone.
eval-retrieval.mjs, 12 everyday questions:
Ranker | Right note first | Right note in top 5 | Expected note in the context pack | Time per question (laptop CPU) |
Keyword only | 42% | 100% | 100% | 2 ms |
Hybrid (default) | 83% | 100% | 100% | about 1.1 s |
eval-hybrid.mjs, 29 harder questions, 11 of them needing two notes and 7 off-topic:
Ranker | Right note first | Right note in top 5 | Off-topic questions refused | Two-note questions with both notes in the context pack |
Keyword only | 77% | 100% | 2 of 7 | – |
Hybrid (default) | 73% | 86% | 6 of 7 | 9 of 11 |
The script follows every note an answer needs through the ranker. On this vault all of them reach the reranker's shortlist; what used to lose them was the last step, which trimmed the second note of a two-note answer and refused some real questions. Two settings fix most of that: a "nothing relevant" floor calibrated per reranker model (bge-reranker-base 0.02, ms-marco-MiniLM 0.001; the two score on very different scales), and keeping at least the five best hits (minKeep). Before them the same set scored 82% in the top 5 and 7 of 11. A third, agreeOverride, is off: answering instead of refusing when keyword and meaning search put the same section first rescues the money-tracker paraphrase here, but also answers off-topic questions that share one rare word with a note, such as "python snake species in india". The off-topic question still answered, "which of Ines's projects runs on Kubernetes", is a near miss: the vault holds related notes, so no floor can tell it apart from a real question. Paraphrase is still the weak spot (issue #3), and a faster reranker is issue #10.
To score your own vault, write cases with the notes each answer needs (required) and the sentences that prove it (evidence: a list of groups, each holding alternative spans of which one must be in the context pack), then run node scripts/eval-hybrid.mjs --config <your config> --cases <your cases>. --set key=value tries another setting (--set rerankN=8), --sweep key=a,b,c compares several in one run, --repeat 2 checks that two runs agree exactly, and --json keeps every result.
Graph visualizer
See your vault the way search sees it. npm run graph exports the link graph, and visualizer/ draws it in an Obsidian-style 2D view or in 3D:
Notes are coloured by meaning (their embeddings), so topics shade into each other.
Line thickness is the bond strength the ranker uses when it follows links.
Hovering a note lights its strongest neighbours in green and fades the rest.
Clicking a note lists its bonds with the sentence that makes each link.
npm run graph
cd visualizer && python3 -m http.server 4750 --bind 127.0.0.1 # open http://127.0.0.1:4750/Import notes from another tool
brain-mcp reads any folder of Markdown, but it reads Obsidian-style frontmatter and [[wikilinks]] best. The importers in scripts/import/ bring notes from other tools into a vault in that form. They only read the source, never change it, and have no dependencies beyond the ones brain-mcp already installs.
node scripts/import/import.mjs logseq ~/logseq-graph --to ~/second-brain
node scripts/import/import.mjs notion ~/notion-export --to ~/second-brain # unzip the "Markdown & CSV" export first
node scripts/import/import.mjs markdown ~/old-notes --to ~/second-brainNotes land in <vault>/Imported/ (--into <folder> changes that). --project "Name" puts every imported note in a project, --dry-run shows what would happen and writes nothing, and a second run skips notes that already exist (so your edits are safe; --force replaces them). Each run ends with a count of what was converted and what was left out. Try one on the fictional samples in scripts/import/sample/.
Source | Converted | Not converted |
Logseq graph ( | Pages and journals; page properties ( | Block references |
Notion export | Pages and subpages with the 32-character IDs removed from names; the title; links between pages as | Database tables ( |
Markdown folder | Folder structure and file names; existing frontmatter kept, with | Links to files that are not notes (kept as they are); the heading part of a link; notes whose frontmatter is not valid YAML are imported without it |
Links and tags inside code blocks and inline code are never rewritten. After an import, run npm run reindex to see the new note count, then node scripts/graph-stats.mjs to see how many links resolved.
Use your own vault
npx debawho-brain-mcp init, or npm run setup in a clone, does this for you. To do it by hand, copy brain.config.json to brain.config.local.json (or ~/.brain-mcp/config.json for the npm package) and change what differs:
{
"vaultPath": "../my-vault",
"dataDir": "./data/local",
"owner": "Your Name",
"privatePaths": ["Private/**", "Journal/**"],
"identity": {
"profileNote": "About me",
"memoryProject": "Assistant Memory",
"skillsProject": "Assistant Skills"
}
}vaultPath and dataDir are resolved relative to the config file. The server uses the first config it finds: --config <path>, then BRAIN_MCP_CONFIG, then brain.config.local.json, then ~/.brain-mcp/config.json (npm package only), then brain.config.json. Run npm run reindex to check the note count; the first log line names the config in use.
Any Markdown file in the vault is indexed. Frontmatter makes it richer:
Field | Used for |
| Display name and title matching. Falls back to the file name. |
|
|
| The project a note belongs to, usually a wikilink to its hub: |
| Concepts the note is about, as wikilinks. Drives the topic filter and shared-topic neighbours. |
| Extra links, added to the graph like body wikilinks. |
| Other names |
|
|
| Date used for recency, |
| Shown next to each hub in the identity bundle. |
Wikilinks in the body ([[Note]], [[Note#Heading]], [[Note|alias]], [[Folder/Note]]) and in frontmatter become graph edges. Each link is recorded with where it sits, because that says how much the author meant it: inside a sentence, in a list item that explains it, as a bare list entry, in a heading or table, in frontmatter, or in a generated ## Connections trailer. Links inside code and embeds of images or other attachments are not links. A target resolves by path (or its end, as in [[Notes/Plan]]), title, file name or alias, ignoring case, .md, extra whitespace, and hyphens or underscores versus spaces; when several notes share a name, the one in the linking note's folder wins, then the shortest path. brain_graph, the links line of brain_read and the warnings of brain_move and brain_delete all follow these rules. In frontmatter, project, topics, related and part-of are links for every tool, plain names included; a [[link]] under any other key counts for the link graph only. A link's strength weighs where it sits, whether it is repeated or written both ways, and how many notes link to its target (a hub linked from everywhere says little); those counts include every note, private ones too, like the word statistics of keyword search, and reveal no note or text. A leading # Title that repeats the title is dropped from what clients read, and a generated ## Connections trailer after a --- rule is left out of search and context.
Profile: the note named by
identity.profileNote, matched by title, alias, path or file name.Memory: every note whose
projectisidentity.memoryProject. Write each one with a How to apply line; the bundle tells the client to follow them.Captured facts: the facts in
memoryFilethat are true now. Replaced, expired and not-yet-valid ones stay in the file and are left out. Over the size cap, who the owner is and how to work with them stay longest, then the newest project and reference facts.Skills: notes in
identity.skillsProject, listed by their first paragraph.Projects: every note with
type: hub.Current focus: content notes modified in the last
identity.focusWindowDaysdays.
The memory file stays plain Markdown and stays append-only: once written, a fact is never edited by the server. A later fact says what it changes, on lines you can read in Obsidian:
## 2026-09-22 18:21 · project
The app uses SQLite.
*via mcp:claude-code*
## 2026-10-16 09:10 · project
The app uses Postgres.
**Key:** the app / database
**Valid from:** 2026-10-01
**Replaces:** 2026-09-22 18:21
*via mcp:claude-code*Ids are the stamps in the headings. Two facts saved in the same minute become
2026-10-16 09:10and2026-10-16 09:10 #2.Replaces ends the named facts when the new one starts (its
Valid from, or when it was recorded). Only earlier facts can be replaced. ASupersedesline from older versions counts the same way.Key (
subject / attribute) makes replacement automatic: a later fact with the same pair, in any letter case, replaces the current one.Valid until ends a temporary fact. A bare date means through that day. Times are UTC.
The index derives a facts table from these lines whenever the file changes, and rebuilds it from the file on every start, so the file is the only copy that matters. To undo a replacement, delete the Replaces line in Obsidian. brain_identity serves the facts true now, brain_facts answers what was true at another date, and brain_context still finds an old fact but marks it as replaced or expired.
Key | Meaning |
| Vault folder, relative to the config file. |
| Folder for the search index and the OAuth database, relative to the config file. Default: |
| Name used in the server instructions and the identity bundle. |
| The only folder the server writes to. |
| File |
| Top-level folders that are never indexed. Any path segment starting with |
| Globs that are never served to anyone. |
| Project names and globs that need the |
|
|
| Profile note, memory and skills projects, focus window and size caps. |
| Hybrid ranking: |
| Folders the write, edit, move and delete tools may change. Default: the capture folder and |
| Host, port and path for HTTP modes. The shipped config uses |
| Mode, public URL, token lifetimes, lockout policy and default scopes for OAuth. |
Environment overrides: BRAIN_MCP_HOME (where the npm package keeps its config, index and logs; default ~/.brain-mcp), BRAIN_MCP_CONFIG, BRAIN_MCP_DATA_DIR, BRAIN_MCP_LOG_DIR, BRAIN_MCP_HOST, BRAIN_MCP_PORT, BRAIN_MCP_AUTH_MODE (token or oauth), BRAIN_MCP_PUBLIC_URL, and BRAIN_MCP_HYBRID=0 to switch back to keyword-only ranking.
Connect a client
Claude Code
claude mcp add --scope user brain -- npx -y debawho-brain-mcp --stdioFrom a clone, run the build instead: claude mcp add --scope user brain -- node /absolute/path/to/brain-mcp/dist/index.js --stdio.
Or commit a .mcp.json to a project so it is available whenever that folder is open:
{
"mcpServers": {
"brain": {
"command": "node",
"args": ["/absolute/path/to/brain-mcp/dist/index.js", "--stdio"]
}
}
}Claude Desktop
Add the same mcpServers block to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) and restart the app.
Hermes Agent
hermes mcp add brain --command npx --args -y debawho-brain-mcp --stdio
hermes mcp test brain # connects and lists the 13 toolsThe tools appear in Hermes as mcp_brain_brain_identity, mcp_brain_brain_context and so on. For the remote server, use hermes mcp add brain --url https://brain.example.com/mcp --auth oauth and sign in once.
Agent skill
skills/brain-mcp is a SKILL.md that teaches an agent to use the server well: load the owner's identity only for their own work, pick the right tool for each question, cite note ids, say when the vault doesn't record something, and write back only with the owner's consent. Copy the folder into your agent's skills directory, for example ~/.claude/skills/brain-mcp/ for Claude Code. It is instructions only, with no scripts.
export BRAIN_MCP_TOKEN="$(node dist/index.js --gen-token)" # keep this somewhere safe
node dist/index.js --http # http://127.0.0.1:3737/mcpBRAIN_MCP_TOKEN grants the read, write and private scopes. BRAIN_MCP_TOKEN_RO grants read only. Tokens shorter than 32 characters are ignored, and the server refuses to start in this mode with no token. It binds to loopback; only expose it over a private network such as Tailscale. Anything public should use --oauth.
--oauth starts the public transport: an OAuth 2.1 authorization server plus the protected /mcp endpoint, meant to listen on loopback behind Cloudflare Tunnel or another TLS-terminating proxy. node scripts/verify-oauth.mjs checks the whole flow end to end.
What a client goes through. Discovery (/.well-known/oauth-protected-resource/mcp → /.well-known/oauth-authorization-server), dynamic client registration at /register (https or loopback redirect URIs only), /authorize with PKCE S256, a login page (password plus a 6-digit authenticator code, both checked every time; five failures pause sign-in for 15 minutes), a consent page listing the scopes, then /token. Access tokens live one hour. Refresh tokens rotate on every use and live 30 days, and presenting a rotated-out refresh token revokes the whole grant. Tokens are opaque and stored only as SHA-256 hashes; the password is stored as an scrypt hash.
On a Linux box (Node 22+). Clone to ~/brain-mcp, put your vault where vaultPath expects it, set auth.publicUrl to your hostname (for example https://brain.example.com), then:
~/brain-mcp/deploy/setup-linux.sh # builds, installs the systemd unit
cd ~/brain-mcp && node dist/index.js auth init # password + QR code for your authenticator app
sudo systemctl start brain-mcpThen follow the Cloudflare Tunnel steps the script prints. deploy/cloudflared-config.yml is the ingress template.
On a Windows box (elevated PowerShell, Node 22+ via winget install OpenJS.NodeJS.LTS). Clone to $HOME\brain-mcp, then:
Set-ExecutionPolicy -Scope Process Bypass -Force
& "$HOME\brain-mcp\deploy\setup-windows.ps1" # builds, registers a boot-time task as SYSTEM, disables sleep
cd $HOME\brain-mcp; node dist\index.js auth init
Start-ScheduledTask -TaskName brain-mcpConnect clients
claude.ai: Settings → Connectors → Add custom connector →
https://brain.example.com/mcp. Sign in once on the page that opens.Claude Code:
claude mcp add --scope user --transport http brain https://brain.example.com/mcp, then run/mcpand authenticate.Anything else that speaks MCP over HTTP with OAuth: the same URL.
Manage access from the box:
node dist/index.js auth status # configured? counts, recent failures
node dist/index.js auth clients # every registered client and its live grants
node dist/index.js auth grants # active refresh grants with last-used time
node dist/index.js auth revoke-client <client_id>
node dist/index.js auth revoke-all
node dist/index.js auth set-password # or rotate-totpKeep the vault fresh on the box with Syncthing, or a git push and a pull on a timer. The watcher picks changes up within a second.
Security model
Transport. stdio inherits the OS user. HTTP needs a bearer token compared in constant time, and each session is bound to the client id that opened it.
Scopes.
brain:read,brain:write,brain:private. Notes markedvisibility: private, or matched byprivateProjectsorprivatePaths, need the private scope.denyPathsare never served. The example vault keeps one note underPrivate/so you can watch this work.Redaction. Credential-shaped strings (Anthropic, OpenAI, GitHub, AWS, Google, Slack and Stripe keys, JWTs, private keys,
password=style assignments, credentials embedded in URLs) are masked as[REDACTED:kind]before they leave the server.Writes are confined to the writable folders (
writableDirs). Generated notes, hidden folders and paths outside the vault are refused, and deletes go to.trash/.Local models. Embeddings and reranking run on your CPU. Note text is never sent to a model service.
Audit. Every call records timestamp, transport, client, session, tool, truncated arguments, note ids returned and redaction count.
Found a vulnerability? Please report it privately, as described in SECURITY.md.
Roadmap
Section-level full-text search with title and graph fusion
Remote access with OAuth 2.1, PKCE, password and authenticator code
Secret redaction, scopes and an audit log
Live index with a file watcher
Hybrid retrieval: local embeddings fused with BM25, a cross-encoder reranker, spelling correction (#1)
Write, edit, move and delete tools for hand-written notes
Calibrate the "nothing relevant" floor so real questions are not refused (#3)
A faster reranker that keeps accuracy (#10)
Graph expansion with Personalized PageRank over wikilinks (#2)
Harder eval questions (#4)
Docker image (#5) —
Dockerfile+docker-compose.yml, see Run with DockerImporters for Logseq, Notion exports and plain Markdown folders (#6), see Import notes from another tool
Passkey sign-in (#7)
Facts that change over time: replacements, expiry and history (#8)
Contributing
brain-mcp is built to be learned from and experimented on, and it needs contributors to succeed. It is a small, readable codebase with a real, measurable problem at its centre: helping an AI find the right note in someone's personal knowledge. If you are learning how MCP servers work, studying retrieval, or researching memory for AI systems, this is a good place to do it, and every improvement you make is measured by the bundled eval.
The architecture is deliberately simple today, so there is plenty of room to reshape it. Proposals to make parts of it configurable or swappable are as welcome as code.
Good for learning
You want to learn | Start here |
How an MCP server exposes tools, resources and prompts |
|
Hybrid search: BM25, embeddings, rank fusion |
|
Running embedding and reranker models on a CPU |
|
Turning wikilinks and frontmatter into a knowledge graph |
|
OAuth 2.1 with PKCE, token rotation and TOTP |
|
Scopes and secret redaction |
|
Evaluating retrieval honestly |
|
Open research questions
Each of these is an open issue with a suggested approach and a definition of done:
When should retrieval abstain? The floor is now calibrated per reranker and refuses plainly off-topic questions. Near misses, where the vault holds related notes but not the answer, still score like real questions: telling them apart needs a check that a passage actually answers the question. (#3)
Which reranker gives the best accuracy per millisecond on a CPU? A model six times faster finds the right note in 58% of everyday questions instead of 75%. (#10)
Can the graph a vault already has replace an LLM-built one for multi-hop questions? (#2)
How should AI memory notice that a fact changed? The memory file now records replacements and expiry, and
brain_factsanswers what was true when. A change the caller does not name is only caught by word overlap within one category; catching it by meaning is open. (#8)How do you evaluate retrieval over personal data without sharing that data? Start with a harder public eval set. (#4)
How to contribute
Pick something. Browse good first issues, research questions or help wanted, or open an issue with your idea.
Run the checks. Everything runs against the bundled example vault, so no personal data is needed.
Measure. If your change touches ranking, run
node scripts/eval-retrieval.mjsbefore and after and paste both into the pull request. Good ideas win on numbers.Open a pull request. CI builds, typechecks and runs every verification script.
Read CONTRIBUTING.md for the details, and please follow the code of conduct.
Citing
If you use brain-mcp in research or teaching, please cite it. GitHub's Cite this repository button uses CITATION.cff.
Project structure
brain-mcp/
├── src/
│ ├── index.ts entry point: init, stdio, --http, --oauth, --reindex
│ ├── tools.ts the 14 MCP tools, resources and prompts
│ ├── context.ts brain_context: fusion and packing under a budget
│ ├── identity.ts the persona bundle
│ ├── memory.ts the memory file's blocks and near-duplicate checks
│ ├── facts.ts facts with validity windows: replacements, expiry, history
│ ├── policy.ts scopes and secret redaction
│ ├── vault/ parsing notes, the SQLite index, hybrid ranking
│ │ └── dense.ts local embeddings and the reranker
│ └── auth/ OAuth 2.1 server, login page, TOTP, token store
├── scripts/ setup, smoke test, verification scripts, retrieval eval, graph export
├── visualizer/ the graph visualizer: one HTML page and its vendored libraries
├── templates/ the starter vault init and npm run setup create
├── example-vault/ a fictional vault used by every script
├── deploy/ Linux and Windows setup, Cloudflare Tunnel template
└── brain.config.json the example vault's config; npm run setup writes yours beside itLicense
MIT. Created by Debashish Thakur.
Available Tools
14 toolsbrain_captureSave a durable noteA
Write a new note into the vault's capture folder with graph-ready frontmatter. Use for plans, decisions, ideas, meeting notes, or session logs the owner wants to keep. Not for one-line facts (use brain_remember). The reply lists existing notes the body names without linking.
Inputs: body (required), title (required), kind, topics, +1 more.
brain_contextGet the vault sections that answer a questionARead-onlyIdempotent
One call that returns the most relevant sections from across the vault for a question, with source note ids. Use this before brain_search when you need to answer or reason about something the owner may have written down. Ask in plain words: retrieval is hybrid (keywords + meaning + a reranker), so paraphrases work; still include specific nouns, ids and dates when you have them. The reply states its coverage (good / thin / none).
Inputs: question (required), project, budget_chars.
brain_deleteDelete a hand-written note (to the vault trash)ADestructive
Remove a note from Notes/ or Captures/ by moving it into the vault's .trash/ folder, which is never indexed. Nothing is erased; the result gives the path to restore from. Generated notes and the memory file cannot be deleted.
Inputs: note (required).
brain_editEdit part of a hand-written noteADestructive
Change part of a note under Notes/ or Captures/ without rewriting it. Give exactly one of: old_text + new_text (old_text must occur exactly once; new_text may be empty), section + content (replaces everything under that heading up to the next heading of the same or higher level; the heading itself stays), or append. Generated notes and the memory file cannot be edited. The reply lists existing notes the new text names without linking.
Inputs: note (required), append, content, section, +2 more.
brain_factsFacts and how they changedARead-onlyIdempotent
Facts recorded with brain_remember and when each was true. By default, the facts true now. as_of returns the facts true at another time (a bare date means the end of that day); history lists every version, oldest first, with what replaced it or when it expired; subject narrows to one thing, e.g. a project; query filters by words. The ids are the ones brain_remember's replaces takes.
Inputs: as_of, limit, query, history, +2 more.
brain_graphExplore the link graphARead-onlyIdempotent
Neighbours of a note, hub, or concept: outgoing links, backlinks, and notes sharing the same topics. For a concept (e.g. 'OAuth') this shows every project that touches it. Use it to hop sideways between projects.
Inputs: note (required), limit.
brain_identityLoad the owner's identity and standing contextARead-onlyIdempotent
Call this FIRST in every conversation. Returns who the owner is, their preferences and feedback rules, the projects they run, and what they touched recently. Adopt it as your persona and working context. Captured facts are only the ones true now; brain_facts has their history. Pass topic (a few words about what the conversation is about) to get a smaller bundle with only the memory notes that apply.
Inputs: topic.
brain_moveMove or rename a hand-written noteADestructive
Move or rename a note within Notes/ and Captures/, for example to promote a capture into Notes/. Refuses to overwrite an existing note, and reports any links that stop resolving.
Inputs: to (required), note (required).
brain_projectProject briefingARead-onlyIdempotent
One-call briefing on a project: what it is, its notes grouped by type, latest progress entries, decisions, and what changed recently. Call this before discussing any project. Omit the project name to list all projects.
Inputs: project, recent_days.
brain_readRead a noteARead-onlyIdempotent
Return one note in full (or one section of it) by note id, title, or wikilink target. Includes frontmatter metadata, topics, and links.
Inputs: note (required), section, include_connections.
brain_recentWhat changed recentlyARead-onlyIdempotent
Notes modified in the last N days, newest first. Answers 'what am I working on' and 'what did I do last week'. Hubs and concepts are excluded unless include_structural is set.
Inputs: days, limit, project, include_structural.
brain_rememberRemember a durable factA
Append one durable fact about the owner to their memory file: a preference, a correction on how to work, a project constraint, or a reference. It becomes part of brain_identity immediately. Include why it matters and how to apply it. When it changes an earlier fact, pass replaces with that fact's id (the stamp in its heading, e.g. '2026-09-22 18:21'): the old fact stays in the file as history and leaves brain_identity. For a fact with one current value, pass subject and attribute (e.g. 'JobMail' and 'database'); a later fact with the same pair replaces it on its own. Use valid_until for something temporary and valid_from when it became true earlier than now. Near-duplicates of current facts are refused, and a fact that looks like it changes a current one is held back until you say whether it replaces it; pass force=true to store it as is. Do not store session trivia.
Inputs: fact (required), category (required), why, force, +6 more.
brain_searchSearch the vaultARead-onlyIdempotent
Full-text search across every note with optional filters. Returns ranked hits with snippets and note ids for brain_read. Keywords or a short question both work (hybrid keyword + semantic search with spelling correction); the reply states its coverage.
Inputs: query (required), type, limit, since, +2 more.
brain_writeCreate or replace a hand-written noteADestructiveIdempotent
Create a note at a path you choose under Notes/ or Captures/, or replace one there with overwrite=true. Use it for hubs, guides and runbooks maintained by hand. Unlike brain_capture you set the type, including 'hub': a hub groups every note whose frontmatter project matches its title. Generated notes elsewhere in the vault cannot be written. The reply lists existing notes the body names without linking.
Inputs: body (required), path (required), title (required), type, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools target clearly distinct operations (read, edit, delete, move, graph, recent), and the descriptions actively steer selection, e.g. brain_context says to use it before brain_search, and brain_capture vs brain_write is spelled out as templated-capture vs hand-maintained note. The remaining fuzzy pairs are retrieval (brain_context vs brain_search) and fact storage (brain_remember vs brain_capture), which are close enough that an agent may still occasionally pick wrong despite the guidance.
Every tool shares the same `brain_` prefix and snake_case, which makes the set easy to scan. The stem after the prefix mixes verbs (search, read, write, edit, delete, move, capture, remember) with nouns (context, identity, facts, project, graph, recent), a minor inconsistency but still predictable and readable.
14 tools is squarely in the well-scoped range, and each one maps to a distinct vault operation rather than a variant of another. Nothing looks redundant or padding-like; the memory, note, and retrieval surfaces all earn their entries.
The note lifecycle is essentially covered: create (capture/write), read, edit, move, delete-to-trash, plus search, graph, recency, project briefings, and fact history. Gaps are modest but real — several descriptions mention notes being named 'without linking' yet there is no link-creation tool, there is no restore-from-trash operation despite delete pointing to one, and there is no way to enumerate or browse the vault by folder or tag.
Maintenance
Related MCP Connectors
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
Notes and memory assistant: one Markdown vault that Claude, ChatGPT and any MCP client can share.
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides semantic search capability over Obsidian vaults and exposes recent notes as resources to Claude through the MCP protocol.9-
- AlicenseAqualityCmaintenanceGive Claude (and any MCP client) real agent access to your Obsidian vault — graph traversal, Dataview queries, daily-note awareness, and more.2519 npm1MIT
- AlicenseNot gradedqualityDmaintenanceProvides semantic search, note retrieval, source explanation, daily digests, and health checks for a local Obsidian vault, enabling MCP clients like Claude Desktop and Claude Code to query the second brain via natural language.MIT
- AlicenseNot gradedqualityBmaintenanceMCP server exposing fast full-text and semantic search over an Obsidian vault, plus safe structured note read and write access for Claude.2Apache 2.0