thebrain

thebrain-mcp

基于 TheBrain 15 本地 API 构建的 MCP 服务，适用于 TheBrain 15。

它为 Agent 提供对脑图的语义操作：按含义搜索、读取图谱中的邻域，以及将拆解后的内容写入脑图，形成完整的关联结构。它并非 API 的镜像——只提供 19 个工具，而非 48 个端点。

重点不是“保存这段文本”。而是当你将一篇文章交给 Agent 时，它会阅读文章、拆解其中的含义，弄清楚每个含义在现有图谱中的归属、应该关联到什么，以及每条笔记应该写些什么。

已在 npm 上发布为 thebrain-mcp-server——npm 认为较短的名称与一个无关的现有包过于相似。安装后的命令仍然是 thebrain-mcp。

要求

• 正在运行且已启用本地 API 的 TheBrain 15
• Node.js 22 或更高版本
• API 密钥：设置 → 用户 → 本地 API 密钥

安装

Claude Code

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

使用配置文件的客户端

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

语义搜索

TheBrain 自带的搜索会匹配前缀：OT 可以找到 OTGP，但同义词或拼写错误则无法匹配。若要按含义搜索，服务会构建本地向量索引。

嵌入包不包含在安装中：它约占 380 MB，首次运行时模型本身还要占 113 MB。请单独安装，且仅在需要时安装：

npm install -g @huggingface/transformers

然后，在客户端中运行 brain_index，并设置 action: "rebuild"。为一个包含 10,000 个想法的脑图建立索引大约需要一分钟；之后只会重新计算发生变化的内容。

不安装该包，服务也能运行。 brain_search 会退而使用 Agent 提供的同义词进行多路前缀查询，并明确提示召回率较低。

所有操作都在本地进行：脑图内容和查询都不会发送到任何地方。

设置

变量	默认值	用途
THEBRAIN_API_KEY	—	必填
THEBRAIN_BASE_URL	http://localhost:11522，然后是 :8001	本地 API 地址
THEBRAIN_DATA_DIR	~/.thebrain-mcp	索引存储位置
THEBRAIN_ALLOW_DESTRUCTIVE	0	允许删除想法和链接
THEBRAIN_EMBEDDING_MODEL	Xenova/multilingual-e5-small	嵌入模型
THEBRAIN_EMBEDDING_DTYPE	q8	权重精度
THEBRAIN_TIMEOUT_MS	30000	API 请求超时时间

更改模型或精度会导致现有索引无法使用——服务会提示这一点，并要求重新构建索引。

通常无需设置 THEBRAIN_BASE_URL。TheBrain 更新后，本地 API 的端口从 8001 改为 11522，因此服务会先尝试新端口，失败后再使用旧端口。仅当 TheBrain 监听其他地址时才需要设置该变量；直接使用设置中显示的端点即可（http://localhost:11522/api/）。

工具

读取

工具	功能
brain_list	查看知识脑、当前打开的是哪一个，以及索引是否就绪
brain_get_thought	一次调用获取一个想法、其别名、关系图和备注
brain_search	按含义搜索
brain_traverse	沿关系图向外遍历数跳
brain_list_types_and_tags	查看知识脑的词汇表
brain_recent_changes	以通俗语言查看更改内容
brain_index	查看索引状态、构建索引和刷新索引

写入

工具	功能
brain_create_thought	创建一个想法，并附上备注、类型、标签和别名
brain_update_thought	更新名称、标签、类型和颜色；添加或移除别名
brain_set_note / brain_append_note	替换或补充备注
brain_link	用标签连接两个想法；使用 replace 可将连接它们的关系改为另一种
brain_unlink	移除关系，需人工确认
brain_tag	添加或移除标签
brain_create_type_or_tag	创建类型或标签；如果知识脑已有同名标签，则返回该标签，不会重复创建
brain_attach_url	添加链接，不会重复添加
brain_activate	在用户的屏幕上打开一个想法
brain_delete_thought	删除想法，需人工确认
brain_ingest	一次调用写入完整结构

brain_ingest

用于填充知识脑的主要工具。Agent 将材料拆分成想法，通过临时标识符将它们连接起来， 然后一次调用即可写入全部内容：

{
  "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" }
  ]
}

输入中想法的顺序无关紧要——依赖关系会自动解析。重复运行同一计划不会产生重复内容；如果某个想法已经存在，则会保留其备注：计划中的备注只会在原本没有备注时写入，结果会指出哪些备注得以保留。无效计划（例如包含循环或引用不存在的内容）会在首次写入之前被拒绝。

技能

服务提供的是机制——确定性的操作。方法论（如何细分含义、何时关联到已有内容、备注中应包含什么）则独立存放在 Claude Code 技能中。这些技能是普通的 Markdown 文件，因此你可以按自己的工作方式进行调整，而无需重新构建服务。

技能	触发时机
thebrain-ingest	“把这篇文章放进我的知识脑”“拆解并记录这段内容”
thebrain-research	“我对 X 了解多少”“我们之前讨论过这个吗？”
thebrain-organize	“整理我的知识脑”“查找重复项”
thebrain-digest	“我这周添加了什么”“我最近一直在做什么”

将它们安装为符号链接，这样仓库中的编辑会立即生效：

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

如果不想保留指向仓库的链接，也可以复制它们。对于单个项目，请在项目根目录中使用 .claude/skills，而不是 ~/.claude/skills。

技能会在会话启动时加载——已在运行的会话需要重启（claude --continue 会保留对话）。

删除

删除想法（brain_delete_thought）和关系（brain_unlink）。默认禁用。即使设置了 THEBRAIN_ALLOW_DESTRUCTIVE=1，仍需获得人工同意：如果客户端支持确认表单，则通过表单确认；否则需通过第二次调用并显式指定标记来确认。Agent 不能替你做这个决定。

开发

npm install
npm test                 # unit tests, no live TheBrain needed
npm run build

针对在线 API 的契约测试：

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

写入测试需要一个单独的临时知识脑，并且拒绝操作包含超过 500 个想法的知识脑。需要读取知识脑的只读测试也会读取该知识脑；如果没有它，则跳过：没有任何测试会读取其他知识脑。

文档

• ARCHITECTURE.md — 服务的构建方式及其原因：各层的边界、机制与策略的分离、错误处理理念、语义层，以及每项决策背后的原因。
• docs/api-map.md — 本地 API 的行为，包括未记录的部分；根据运行中的实例验证，并附有测量数据。
• docs/stack-evaluation.md — 选择 TypeScript 的原因，并附有数据。
• CONTRIBUTING.md — 如何参与开发。

支持

thebrain-mcp 是利用业余时间构建和维护的。如果它能成为你工作流的一部分，你可以在 GitHub 上赞助它——一次性赞助或按月赞助均可。

许可证

MIT