TheBrain MCP & API Server

将 TheBrain 知识图谱接口封装为 MCP (Model Context Protocol) 服务器和 RESTful API，支持 AI 助手集成和自定义开发。

特性

• 🧠 MCP 协议支持 - 可集成到 Claude Desktop、Cursor 等 AI 工具

• 🌐 RESTful API - 22 个完整的 HTTP 接口

• 🔍 增强搜索 - 丰富的返回字段，支持原始结果查询

• 📌 置顶管理 - 想法置顶/取消置顶

• 🔗 链接操作 - 查看和更新想法间的链接关系

• 📊 统计信息 - 获取大脑统计数据和修改日志

• 🐳 Docker 支持 - 一键部署

Related MCP server: obsidian-local-mcp

快速开始

使用 Docker (推荐)

# 1. 设置环境变量
cp .env.example .env
# 编辑 .env 填入：
# - THEBRAIN_API_KEY
# - THEBRAIN_BRAIN_ID

# 2. 启动服务
docker-compose up -d

# 3. 访问
# API 文档: http://localhost:8000/docs
# MCP 端点: http://localhost:8000/mcp/mcp

本地开发

# 1. 创建环境
conda create -n thebrain-mcp python=3.10 -y
conda activate thebrain-mcp

# 2. 安装依赖
pip install -r requirements.txt

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env

# 4. 启动服务
python api_server.py

API 接口

🔐 认证说明

所有 /api/* 接口都需要 Bearer Token 认证，使用您的 THEBRAIN_API_KEY 作为 token：

curl -H "Authorization: Bearer YOUR_THEBRAIN_API_KEY" \
  http://localhost:8000/api/pins

📋 完整接口列表

搜索相关

想法操作

链接操作

笔记操作

元数据

附件操作

大脑统计

总计: 28 个 RESTful API 接口

查看完整文档和在线测试: http://localhost:8000/docs

MCP 集成

MCP 工具列表

🌟 高级工具使用指南

以下工具专为知识发现和智能分析设计,推荐 AI 优先使用:

1. get_graph - 查看知识关系网络 ⭐

适用场景: 了解一个想法的完整关联关系

返回内容:

• ✅ 自动包含 typeName - 想法会显示类型名称(如"项目"、"任务")

• 想法的所有关联: parents(父节点)、children(子节点)、jumps(跳转链接)、siblings(兄弟节点)

• links 数组: 包含链接的基本信息(简化版)

  • relation - 关系类型(1=Child, 2=Parent, 3=Jump, 4=Sibling) ⭐

  • meaning - 链接语义(1=Normal, 2=InstanceOf, 5=HasTag 等) ⭐

  • thickness - 链接粗细(-1=默认, 1-5=用户设置) ⭐

  • typeId - 链接类型ID(⚠️ 无法获取类型名称)

  • ❌ 不包含: name(标签)、color(颜色)

• attachments(附件列表)

最佳实践:

用户: "帮我分析一下 '项目A' 的知识结构"
AI: 使用 get_graph 获取完整图谱
    - 查看 activeThought.typeName 了解想法类型(如"项目")
    - 查看 links[].relation 了解关系方向(1=子,2=父,3=跳转,4=兄弟)
    - 查看 links[].meaning 了解语义(1=普通,5=标签等)
    - 查看 links[].thickness 识别重要链接(数值越大越重要)
    - 如需查看链接的 name 和 color,使用 get_link_between

2. get_link_between - 查看两节点间的链接详情 🆕

适用场景: 需要查看链接的完整信息(name、color等)时使用

核心参数:

• detailed: 是否返回详细信息,默认 False(简化版,更快速)

返回内容:

• 简化版(默认): relation, meaning, thickness, name, color, typeId

• 详细版(detailed=True): 所有字段(包括 direction、创建时间等)

最佳实践:

用户: "这两个想法之间是什么关系?"
AI: 使用 get_link_between(thought_id_a, thought_id_b)  # 默认简化版,快速
    - 查看 name 了解用户定义的关系标签
    - 查看 color 了解可视化标记
    - 查看 thickness 了解重要程度
    
用户: "给我这个链接的所有详细信息"
AI: 使用 get_link_between(thought_id_a, thought_id_b, detailed=True)
    - 返回包含创建时间、修改时间、direction 等所有字段

3. get_context - 一站式获取完整信息 🎯

适用场景: 需要全面了解一个想法时使用,比 get_graph 更高层

返回内容:

• 想法详情(包含 typeName)

• 完整笔记内容(markdown 格式)

• 所有关联节点分类汇总(每个节点都包含 typeName)

• 统计信息(关联数量)

最佳实践:

用户: "总结一下这个想法的所有内容"
AI: 用 get_context 一次获取所有信息,无需多次调用

4. explore_neighbors - 多层知识探索 🔍

适用场景: 发现深层次的知识关联,适合"扩散式"思维导图

核心参数:

• depth: 探索深度 1-3 层(默认 2 层)

• include_notes: 是否显示第一层的笔记预览

返回内容:

• 递归的层级结构

• 每层节点都包含 typeName

• 可选的笔记摘要

最佳实践:

用户: "帮我找找这个想法相关的所有概念"
AI: 使用 explore_neighbors(depth=3) 深入探索,发现间接关联

5. recent_thoughts - 发现最新变化 ⏰

适用场景: 了解用户最近在思考什么

核心参数:

• days: 最近几天(默认 7 天)

• max_results: 返回数量(默认 20)

最佳实践:

用户: "最近我都在研究什么?"
AI: 用 recent_thoughts(days=7) 快速找到最近活跃的想法

6. find_related - 多关键词智能匹配 🧠

适用场景: 根据多个关键词找相关内容,自动按匹配度排序

特点:

• 匹配多个关键词的想法会排在前面

• 返回匹配分数和匹配的关键词列表

最佳实践:

用户: "找一下关于 'Python' 和 'API' 的内容"
AI: 用 find_related(keywords="Python,API") 找到同时相关的想法

7. search_by_type - 按类型精准过滤 🎨

适用场景: 只想查看某种类型的想法

核心参数:

• type_id: 类型 ID(可选)

• tag_id: 标签 ID(可选)

• query: 搜索关键词(可选)

最佳实践:

用户: "列出所有项目类型的想法"
AI: 先用 list_metadata(category="types") 找到 "项目" 的 type_id
    再用 search_by_type(type_id=xxx) 精准过滤

8. batch_replace_note - 批量更新笔记 ✏️

适用场景: 需要在笔记中批量替换文本

参数格式:

replacements: '[["旧文本1","新文本1"],["旧文本2","新文本2"]]'

最佳实践:

用户: "把所有笔记中的 'TODO' 改成 'DONE'"
AI: 用 batch_replace_note 一次完成,返回替换统计

💡 组合使用技巧

场景1: 深入分析某个主题

1. search_thoughts 找到目标想法

2. get_context 获取完整信息

3. explore_neighbors 发现相关概念

场景2: 发现知识关联

1. find_related 根据多关键词找相关内容

2. get_graph 查看每个想法的 links(包含 typeName)

3. 分析 link 的 relation 和 typeName 理解关系类型

场景3: 类型化知识管理

1. list_metadata(category="types") 查看所有类型

2. search_by_type 按类型筛选

3. get_graph 查看想法时,links 和 thoughts 都会显示 typeName

MCP 认证

⚠️ 新增: MCP 服务器现在也支持 Bearer Token 认证，使用与 RESTful API 相同的 THEBRAIN_API_KEY。

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "thebrain": {
      "url": "http://localhost:8000/mcp/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_THEBRAIN_API_KEY"
      }
    }
  }
}

n8n 集成

在 n8n 中添加 MCP Client 节点，配置如下：

• Connection Type: Streamable HTTP

• URL: http://localhost:8000/mcp/mcp

• Authentication: 在 Headers 中添加 Authorization: Bearer YOUR_THEBRAIN_API_KEY

注意: 确保所有工具参数都有明确的类型定义。如果遇到 Cannot read properties of undefined (reading 'inputType') 错误，请检查 MCP 服务器版本是否最新。

传输协议: 使用 HTTP Streamable 协议（推荐），支持高效双向通信

技术栈

• FastMCP - MCP 协议实现 (锁定 <3 版本)

• FastAPI - RESTful API 框架

• Requests - TheBrain API 客户端

项目结构

.
├── scripts/
│   ├── client.py          # TheBrain API 客户端
│   └── thebrain.py        # CLI 工具
├── mcp_server.py          # MCP 服务器
├── api_server.py          # FastAPI 服务器
├── Dockerfile             # Docker 镜像
├── docker-compose.yml     # Docker Compose 配置
└── requirements.txt       # Python 依赖

环境变量

THEBRAIN_API_KEY=your-api-key-here  # 用于访问 TheBrain API 和保护本服务的 RESTful API
THEBRAIN_BRAIN_ID=your-brain-id-here

⚠️ 注意: THEBRAIN_API_KEY 同时用于：

1. 访问 TheBrain 官方 API

2. 保护本服务的 RESTful API（作为 Bearer Token）

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！