Skip to content
MCP server

Thebrain

Semantic search, graph traversal and batch writes for your TheBrain notes

Runs locallyStatus and history
Install
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-server

Add 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 KeyRequired
  • THEBRAIN_BASE_URLAddress of the local API. Default http://localhost:11522, then http://localhost:8001 for older TheBrain builds
  • THEBRAIN_DATA_DIRWhere semantic indexes are stored. Default ~/.thebrain-mcp
  • THEBRAIN_ALLOW_DESTRUCTIVESet to 1 to allow deleting thoughts. Deletion still requires human confirmation. Default 0
  • THEBRAIN_EMBEDDING_MODELEmbedding model for semantic search. Default Xenova/multilingual-e5-small
  • THEBRAIN_EMBEDDING_DTYPEWeight precision: fp32, fp16, q8 or q4. Default q8
  • THEBRAIN_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.

How AIPoweredBot checks servers