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_remember and brain_capture turn 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["13 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)" .-> V

1. Index. 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.

2. 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.

   • Rerank the best candidates with a cross-encoder (bge-reranker-base). When keyword and meaning search agree on the top hit, only the top 3 are reranked.

   • Decide: if even the best passage scores below a floor, answer "nothing relevant"; otherwise return the strong hits, cited by note, with a coverage label (good, thin, none).

3. 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.

4. Remember and write. brain_remember appends durable facts and refuses near duplicates. 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.

Tools

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 init

It lists the Obsidian vaults on your machine and asks which one to serve (or makes a starter vault in ~/second-brain), asks your name, fetches the two search models once (about 300 MB), 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?"

To connect a client yourself, Claude Code:

claude mcp add --scope user brain -- npx -y debawho-brain-mcp --stdio

Hermes Agent:

hermes mcp add brain --command npx --args -y debawho-brain-mcp --stdio

Claude 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.mjs

The 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 setup

The 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-memory.mjs   # brain_remember dedupe, topic 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-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/eval-retrieval.mjs  # 12 questions, keyword vs hybrid
node scripts/eval-hybrid.mjs     # 15 harder questions: paraphrase, typo, identifier, date, multi-hop, alias, off-topic
node scripts/debug-rank.mjs "your question"   # trace one query through every ranking step

If 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.

export BRAIN_MCP_TOKEN="$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")"
docker compose up --build

The 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:

eval-hybrid.mjs, 15 harder questions:

Hybrid search puts the right note first far more often and refuses questions the vault cannot answer. Its weak spot is the "nothing relevant" floor: on these short example notes it also refuses some real questions, such as "the raspberry pi overheating in the sun". Calibrating that floor is issue #3, and a faster reranker is issue #10. When you point the server at your own vault, replace the cases with questions about your notes.

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:

Wikilinks in the body ([[Note]], [[Note#Heading]], [[Note|alias]]) become graph edges. 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 project is identity.memoryProject. Write each one with a How to apply line; the bundle tells the client to follow them.

• Captured facts: the file at memoryFile, which brain_remember appends to.

• 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.focusWindowDays days.

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 --stdio

From 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 tools

The 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.

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/mcp

BRAIN_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-mcp

Then 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-mcp

Connect 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 /mcp and 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-totp

Keep 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 marked visibility: private, or matched by privateProjects or privatePaths, need the private scope. denyPaths are never served. The example vault keeps one note under Private/ 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 Docker

• Importers for other note tools (#6)

• Passkey sign-in (#7)

• Temporal memory (#8)

Contributing

Good for learning

Open research questions

Each of these is an open issue with a suggested approach and a definition of done:

• When should retrieval abstain? Hybrid search refuses all off-topic questions, but also some real ones. Calibrating the floor is open. (#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 handle facts that change over time? (#8)

• How do you evaluate retrieval over personal data without sharing that data? Start with a harder public eval set. (#4)

How to contribute

1. Pick something. Browse good first issues, research questions or help wanted, or open an issue with your idea.

2. Run the checks. Everything runs against the bundled example vault, so no personal data is needed.

3. Measure. If your change touches ranking, run node scripts/eval-retrieval.mjs before and after and paste both into the pull request. Good ideas win on numbers.

4. 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 13 MCP tools, resources and prompts
│   ├── context.ts        brain_context: fusion and packing under a budget
│   ├── identity.ts       the persona bundle
│   ├── memory.ts         brain_remember and near-duplicate checks
│   ├── 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
├── 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 it

License

MIT. Created by Debashish Thakur.