Thebrain
Semantic search, graph traversal and batch writes for your TheBrain notes
- Pricing
- Open source
- Platforms
- CLI, macOS, Windows
- Runs
- Locally
- Version
- 0.3.0
- Listing updated
- today
Similar MCP servers
About Thebrain
Thebrain is an open-source MCP server for knowledge and memory. It runs locally on your machine and is started by your AI client.
TheBrain 15 is a graph-based notes app, and this server reaches it through its local API with 19 tools instead of mirroring all 48 endpoints. Its aim is that an agent reads an article, breaks it into meanings, finds where each belongs in your existing graph and writes the whole connected structure in one call.
That last step is brain_ingest, which takes thoughts wired together through temporary IDs, resolves dependencies in any order, and rejects bad plans such as cycles before the first write. Rerunning a plan duplicates nothing and existing notes are kept. Search by meaning uses a local vector index built from an optional embeddings package of about 380 MB; without it, search falls back to prefix queries over synonyms the agent supplies, with lower recall. Nothing is sent off your machine.
Deleting thoughts and links is off by default and still needs human confirmation. Four optional Claude Code skills cover ingesting, researching, organising and digesting a brain. It needs TheBrain 15, Node.js 22 or newer and a local API key.
Install
Run in a terminal
claude mcp add thebrain --env THEBRAIN_API_KEY='<THEBRAIN_API_KEY>' -- npx -y thebrain-mcp-serverAdd to claude_desktop_config.json
{
"mcpServers": {
"thebrain": {
"command": "npx",
"args": [
"-y",
"thebrain-mcp-server"
],
"env": {
"THEBRAIN_API_KEY": "<THEBRAIN_API_KEY>"
}
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"thebrain": {
"command": "npx",
"args": [
"-y",
"thebrain-mcp-server"
],
"env": {
"THEBRAIN_API_KEY": "<THEBRAIN_API_KEY>"
}
}
}
}Add to .vscode/mcp.json
{
"servers": {
"thebrain": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"thebrain-mcp-server"
],
"env": {
"THEBRAIN_API_KEY": "<THEBRAIN_API_KEY>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"thebrain": {
"command": "npx",
"args": [
"-y",
"thebrain-mcp-server"
],
"env": {
"THEBRAIN_API_KEY": "<THEBRAIN_API_KEY>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"thebrain": {
"command": "npx",
"args": [
"-y",
"thebrain-mcp-server"
],
"env": {
"THEBRAIN_API_KEY": "<THEBRAIN_API_KEY>"
}
}
}
}Using several servers? Build one config file with the MCP config generator.
Configuration
THEBRAIN_API_KEYLocal API key from TheBrain: Settings > User > Local API KeyRequiredTHEBRAIN_BASE_URLAddress of the local API. Default http://localhost:11522, then http://localhost:8001 for older TheBrain buildsTHEBRAIN_DATA_DIRWhere semantic indexes are stored. Default ~/.thebrain-mcpTHEBRAIN_ALLOW_DESTRUCTIVESet to 1 to allow deleting thoughts. Deletion still requires human confirmation. Default 0THEBRAIN_EMBEDDING_MODELEmbedding model for semantic search. Default Xenova/multilingual-e5-smallTHEBRAIN_EMBEDDING_DTYPEWeight precision: fp32, fp16, q8 or q4. Default q8THEBRAIN_TIMEOUT_MSAPI request timeout in milliseconds. Default 30000
Tools this server provides (19)
Taken from the project documentation; the running server may differ.
- brain_list
- List brains, the open one and index readiness.
- brain_get_thought
- A thought with aliases, graph and note.
- brain_search
- Search by meaning.
- brain_traverse
- Walk the graph several hops out.
- brain_list_types_and_tags
- The brain's vocabulary.
- brain_recent_changes
- What changed, in plain language.
- brain_index
- Index status, build and refresh.
- brain_create_thought
- Create a thought with note, type, tags and aliases.
- brain_update_thought
- Update name, label, type or aliases.
- brain_set_note
- Replace a note.
- brain_append_note
- Extend a note.
- brain_link
- Connect two thoughts.
- brain_unlink
- Remove a link with human confirmation.
- brain_tag
- Attach and detach tags.
- brain_create_type_or_tag
- Create a type or tag.
- brain_attach_url
- Attach a link without duplicates.
- brain_activate
- Open a thought on screen.
- brain_delete_thought
- Delete a thought with human confirmation.
- brain_ingest
- Write a whole structure in one call.
What it does
- Semantic search
- Find thoughts by meaning using a local vector index.
- Graph traversal
- Walk the graph several hops from a thought.
- Whole-structure ingest
- Write a connected set of thoughts in one idempotent call.
- Note editing
- Create, update, set and append notes, tags and aliases.
- Guarded deletion
- Deletes are off by default and need human consent.
- Local only
- Content and queries are not sent anywhere.
Good for
- Turn an article into linked thoughts in your brain
- Ask what you already know about a topic
- Find duplicate or messy thoughts to clean up
- Review what you added this week
Pricing
Open source
Open source npm package; requires TheBrain 15
Thebrain FAQ
What do I need to run it?
TheBrain 15 with the local API enabled, Node.js 22 or newer and a local API key.
Is semantic search required?
No, it falls back to prefix queries with lower recall.
Can the agent delete things?
Only if THEBRAIN_ALLOW_DESTRUCTIVE=1 is set, and a human still confirms.
Is my data sent to a cloud?
No, everything runs locally.
Is Thebrain free?
Yes. Thebrain is open source, so you can use and self-host it for free.
How do I add Thebrain to Claude Code?
Run this command in your terminal: claude mcp add thebrain --env THEBRAIN_API_KEY='<THEBRAIN_API_KEY>' -- npx -y thebrain-mcp-server
What are the best alternatives to Thebrain?
The closest alternatives to Thebrain are Codebase Memory, XERJ, Ha MCP, Claude Code Ultimate Guide and Concord MCP.
Where this comes from
- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.



