{
  "markdown": "# thebrain-mcp\n\nAn MCP server for [TheBrain 15](https://www.thebrain.com/), built on its local API.\n\nIt gives an agent semantic operations over your brain: search by meaning, read a\nneighbourhood of the graph, and write a decomposed piece of material into the\nbrain as a whole connected structure. It is not a mirror of the API — 17 tools\ninstead of 48 endpoints.\n\nThe point is not \"save this text\". The point is that when you hand an agent an\narticle, it reads it, breaks it into meanings, works out where each one belongs\nin the graph you already have, what to link it to, and what each note should say.\n\n> Published on npm as **`thebrain-mcp-server`** — npm considers the shorter name\n> too close to an unrelated existing package. The installed command is still\n> `thebrain-mcp`.\n\n## Requirements\n\n- TheBrain 15 running, with the local API enabled\n- Node.js 22 or newer\n- An API key: **Settings → User → Local API Key**\n\n## Install\n\n### Claude Code\n\n```\nclaude mcp add thebrain -e THEBRAIN_API_KEY=your-key -- npx -y thebrain-mcp-server\n```\n\n### Clients with a config file\n\n```json\n{\n  \"mcpServers\": {\n    \"thebrain\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"thebrain-mcp-server\"],\n      \"env\": { \"THEBRAIN_API_KEY\": \"your-key\" }\n    }\n  }\n}\n```\n\n## Semantic search\n\nTheBrain's own search matches prefixes: `OT` finds `OTGP`, while a synonym or a\ntypo finds nothing. To search by meaning, the server builds a local vector index.\n\nThe embeddings package is **not part of the install**: it weighs around 380 MB,\nplus 113 MB for the model itself on first run. Install it separately, and only if\nyou want it:\n\n```\nnpm install -g @huggingface/transformers\n```\n\nThen, from your client: `brain_index` with `action: \"rebuild\"`. Indexing a\n10,000-thought brain takes about a minute; later runs only recompute what changed.\n\n**The server works without the package.** `brain_search` falls back to a fan-out\nof prefix queries over the synonyms the agent supplies, and says plainly that\nrecall is lower.\n\nEverything is local: neither your brain's contents nor your queries are sent\nanywhere.\n\n## Settings\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `THEBRAIN_API_KEY` | — | Required |\n| `THEBRAIN_BASE_URL` | `http://localhost:8001` | Local API address |\n| `THEBRAIN_DATA_DIR` | `~/.thebrain-mcp` | Where indexes are stored |\n| `THEBRAIN_ALLOW_DESTRUCTIVE` | `0` | Allow deleting thoughts |\n| `THEBRAIN_EMBEDDING_MODEL` | `Xenova/multilingual-e5-small` | Embedding model |\n| `THEBRAIN_EMBEDDING_DTYPE` | `q8` | Weight precision |\n| `THEBRAIN_TIMEOUT_MS` | `30000` | API request timeout |\n\nChanging the model or the precision makes an existing index unusable — the server\nwill say so and ask for a rebuild.\n\n## Tools\n\n**Reading**\n\n| Tool | What it does |\n|---|---|\n| `brain_list` | Brains, which one is open, whether the index is ready |\n| `brain_get_thought` | A thought, its graph and its note in one call |\n| `brain_search` | Search by meaning |\n| `brain_traverse` | Walk the graph several hops out |\n| `brain_list_types_and_tags` | The brain's vocabulary |\n| `brain_recent_changes` | What changed, in plain language |\n| `brain_index` | Index status, build and refresh |\n\n**Writing**\n\n| Tool | What it does |\n|---|---|\n| `brain_create_thought` | A thought together with its note, type and tags |\n| `brain_update_thought` | Name, label, type, colours |\n| `brain_set_note` / `brain_append_note` | Replace or extend a note |\n| `brain_link` | Connect two thoughts, with a label |\n| `brain_tag` | Attach and detach tags |\n| `brain_attach_url` | Attach a link, without duplicates |\n| `brain_activate` | Open a thought on the user's screen |\n| `brain_delete_thought` | Delete, with human confirmation |\n| `brain_ingest` | Write a whole structure in one call |\n\n### `brain_ingest`\n\nThe main tool for filling a brain. The agent breaks material into thoughts, wires\nthem together through temporary identifiers, and the whole thing lands in one call:\n\n```json\n{\n  \"brainId\": \"…\",\n  \"thoughts\": [\n    { \"tempId\": \"art\",   \"name\": \"Article on RAG\", \"parent\": \"<uuid of an existing thought>\" },\n    { \"tempId\": \"embed\", \"name\": \"Embeddings\", \"parent\": \"art\", \"note\": \"…\" },\n    { \"tempId\": \"store\", \"name\": \"Vector store\", \"parent\": \"art\" }\n  ],\n  \"links\": [\n    { \"from\": \"embed\", \"to\": \"store\", \"name\": \"is written into\" }\n  ]\n}\n```\n\nThe order of thoughts in the input does not matter — dependencies resolve\nthemselves. Running the same plan twice duplicates nothing. Bad plans (a cycle, a\nreference to nowhere) are rejected **before** the first write.\n\n## Skills\n\nThe server provides the mechanism — deterministic operations. The methodology\n(how finely to split meanings, when to attach to something that already exists,\nwhat belongs in a note) lives separately, in Claude Code skills. They are plain\nmarkdown files, so you can adjust them to your own way of working without\nrebuilding the server.\n\n| Skill | When it fires |\n|---|---|\n| `thebrain-ingest` | \"put this article in my brain\", \"break this down and record it\" |\n| `thebrain-research` | \"what do I know about X\", \"have we discussed this already?\" |\n| `thebrain-organize` | \"clean up my brain\", \"find duplicates\" |\n| `thebrain-digest` | \"what did I add this week\", \"what have I been working on\" |\n\nInstall them as symlinks, so edits in the repository take effect immediately:\n\n```bash\nmkdir -p ~/.claude/skills\nfor d in skills/*/; do\n  ln -sfn \"$PWD/$d\" ~/.claude/skills/\"$(basename \"$d\")\"\ndone\n```\n\nOr copy them, if you do not want the link to the repository. For a single\nproject, use `.claude/skills` in its root instead of `~/.claude/skills`.\n\nSkills are picked up when a session starts — an already running session needs a\nrestart (`claude --continue` keeps the conversation).\n\n## Deletion\n\nOff by default. Even with `THEBRAIN_ALLOW_DESTRUCTIVE=1` it requires human\nconsent: through a confirmation form if the client supports one, otherwise\nthrough a second call with an explicit flag. The agent cannot make this decision\nfor you.\n\n## Development\n\n```\nnpm install\nnpm test                 # unit tests, no live TheBrain needed\nnpm run build\n```\n\nContract tests against a live API:\n\n```\nTHEBRAIN_API_KEY=… npm test                                  # read-only\nTHEBRAIN_API_KEY=… THEBRAIN_TEST_BRAIN_ID=<uuid> npm test    # + writes\n```\n\nThe write tests require a **separate, throwaway brain** and refuse to touch any\nbrain with more than 500 thoughts.\n\n## Documentation\n\n- [`ARCHITECTURE.md`](ARCHITECTURE.md) — how the server is built and why: layer\n  boundaries, the mechanism/policy split, error philosophy, the semantic layer,\n  and the measurements behind each decision.\n- [`docs/api-map.md`](docs/api-map.md) — the local API's behaviour, including the\n  undocumented parts, verified against a live instance.\n- [`docs/stack-evaluation.md`](docs/stack-evaluation.md) — why TypeScript, with\n  numbers.\n- [`CONTRIBUTING.md`](CONTRIBUTING.md) — how to work on this.\n\n## License\n\nMIT\n",
  "bytes": 6942,
  "sha": "7d3e111e8f666d3345852605a53a59d082e9db782648b9197c28729b29d163f2",
  "repo_slug": "ybookoff/thebrain-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ybookoff_thebrain_ded4ab93/readme"
}