# Thebrain

> Thebrain is an open-source MCP server for knowledge and memory. Semantic search, graph traversal and batch writes for your TheBrain notes. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Windows, Linux
- **Repository:** https://github.com/ybookoff/thebrain-mcp
- **MCP Registry name:** io.github.yBookoff/thebrain
- **Categories:** [knowledge and memory](https://ai-powered.com/categories/knowledge-and-memory), [productivity](https://ai-powered.com/categories/productivity)
- **Listing updated:** 2026-11-18

## About

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.

## Features

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

## Install

### Claude Code (Terminal)

```sh
claude mcp add thebrain --env THEBRAIN_API_KEY='<THEBRAIN_API_KEY>' -- npx -y thebrain-mcp-server
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "thebrain": {
      "command": "npx",
      "args": [
        "-y",
        "thebrain-mcp-server"
      ],
      "env": {
        "THEBRAIN_API_KEY": "<THEBRAIN_API_KEY>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "thebrain": {
      "command": "npx",
      "args": [
        "-y",
        "thebrain-mcp-server"
      ],
      "env": {
        "THEBRAIN_API_KEY": "<THEBRAIN_API_KEY>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "thebrain": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "thebrain-mcp-server"
      ],
      "env": {
        "THEBRAIN_API_KEY": "<THEBRAIN_API_KEY>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "thebrain": {
      "command": "npx",
      "args": [
        "-y",
        "thebrain-mcp-server"
      ],
      "env": {
        "THEBRAIN_API_KEY": "<THEBRAIN_API_KEY>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "thebrain": {
      "command": "npx",
      "args": [
        "-y",
        "thebrain-mcp-server"
      ],
      "env": {
        "THEBRAIN_API_KEY": "<THEBRAIN_API_KEY>"
      }
    }
  }
}
```

## Tools

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

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

## Alternatives

- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ha MCP](https://ai-powered.com/mcp/ha-mcp): Ha MCP is an open-source MCP server for productivity.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.
- [NeuroStack](https://ai-powered.com/mcp/neurostack): NeuroStack is a freemium MCP server for knowledge and memory.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.

---
Source: https://ai-powered.com/mcp/thebrain
