Thebrain

thebrain-mcp

An MCP server for TheBrain 15, built on its local API.

It gives an agent semantic operations over your brain: search by meaning, read a neighbourhood of the graph, and write a decomposed piece of material into the brain as a whole connected structure. It is not a mirror of the API — 19 tools instead of 48 endpoints.

The point is not "save this text". The point is that when you hand an agent an article, it reads it, breaks it into meanings, works out where each one belongs in the graph you already have, what to link it to, and what each note should say.

Published on npm as thebrain-mcp-server — npm considers the shorter name too close to an unrelated existing package. The installed command is still thebrain-mcp.

Requirements

• TheBrain 15 running, with the local API enabled
• Node.js 22 or newer
• An API key: Settings → User → Local API Key

Install

Claude Code

claude mcp add thebrain -e THEBRAIN_API_KEY=your-key -- npx -y thebrain-mcp-server

Clients with a config file

{  "mcpServers": {    "thebrain": {      "command": "npx",      "args": ["-y", "thebrain-mcp-server"],      "env": { "THEBRAIN_API_KEY": "your-key" }    }  }}

Semantic search

TheBrain's own search matches prefixes: OT finds OTGP, while a synonym or a typo finds nothing. To search by meaning, the server builds a local vector index.

The embeddings package is not part of the install: it weighs around 380 MB, plus 113 MB for the model itself on first run. Install it separately, and only if you want it:

npm install -g @huggingface/transformers

Then, from your client: brain_index with action: "rebuild". Indexing a 10,000-thought brain takes about a minute; later runs only recompute what changed.

The server works without the package. brain_search falls back to a fan-out of prefix queries over the synonyms the agent supplies, and says plainly that recall is lower.

Everything is local: neither your brain's contents nor your queries are sent anywhere.

Settings

Changing the model or the precision makes an existing index unusable — the server will say so and ask for a rebuild.

THEBRAIN_BASE_URL rarely needs setting. A TheBrain update moved the local API from port 8001 to 11522, so the server tries the new port and falls back to the old one. Set the variable only if TheBrain listens somewhere else; the endpoint exactly as Settings shows it (http://localhost:11522/api/) is fine.

Tools

Reading

Writing

brain_ingest

The main tool for filling a brain. The agent breaks material into thoughts, wires them together through temporary identifiers, and the whole thing lands in one call:

{  "brainId": "…",  "thoughts": [    { "tempId": "art",   "name": "Article on RAG", "parent": "<uuid of an existing thought>" },    { "tempId": "embed", "name": "Embeddings", "parent": "art", "note": "…" },    { "tempId": "store", "name": "Vector store", "parent": "art" }  ],  "links": [    { "from": "embed", "to": "store", "name": "is written into" }  ]}

The order of thoughts in the input does not matter — dependencies resolve themselves. Running the same plan twice duplicates nothing, and a thought that was already there keeps the note it has: a plan's note is written only where there is none, and the result says which notes were kept. Bad plans (a cycle, a reference to nowhere) are rejected before the first write.

Skills

The server provides the mechanism — deterministic operations. The methodology (how finely to split meanings, when to attach to something that already exists, what belongs in a note) lives separately, in Claude Code skills. They are plain markdown files, so you can adjust them to your own way of working without rebuilding the server.

Install them as symlinks, so edits in the repository take effect immediately:

mkdir -p ~/.claude/skillsfor d in skills/*/; do  ln -sfn "$PWD/$d" ~/.claude/skills/"$(basename "$d")"done

Or copy them, if you do not want the link to the repository. For a single project, use .claude/skills in its root instead of ~/.claude/skills.

Skills are picked up when a session starts — an already running session needs a restart (claude --continue keeps the conversation).

Deletion

Of a thought (brain_delete_thought) and of a link (brain_unlink). Off by default. Even with THEBRAIN_ALLOW_DESTRUCTIVE=1 it requires human consent: through a confirmation form if the client supports one, otherwise through a second call with an explicit flag. The agent cannot make this decision for you.

Development

npm installnpm test                 # unit tests, no live TheBrain needednpm run build

Contract tests against a live API:

THEBRAIN_API_KEY=… npm test                                  # read-onlyTHEBRAIN_API_KEY=… THEBRAIN_TEST_BRAIN_ID=<uuid> npm test    # + writes

The write tests require a separate, throwaway brain and refuse to touch any brain with more than 500 thoughts. The read-only tests that need a brain read that one too, and skip without it: no test reads another brain.

Documentation

• ARCHITECTURE.md — how the server is built and why: layer boundaries, the mechanism/policy split, error philosophy, the semantic layer, and the reasons behind each decision.
• docs/api-map.md — the local API's behaviour, including the undocumented parts, verified against a live instance, with the measurements.
• docs/stack-evaluation.md — why TypeScript, with numbers.
• CONTRIBUTING.md — how to work on this.

Support

thebrain-mcp is built and maintained in spare time. If it earns a place in your workflow, you can sponsor it on GitHub — once or monthly.

License

MIT