Bear MCP

🚀 Bear MCP Server

Bear MCP Server 是一个 MCP（模型上下文协议）服务器，用于将 Bear 笔记应用与 Claude Desktop 集成。借助该服务器，Claude 能够直接读取、创建和搜索你的 Bear 笔记。

✨ 主要特性（v4.0.2）

具备完整的数据检索能力：

• 🔍 搜索笔记，并获取包含元数据的完整结果
• 🏷️ 检索所有标签，从你的 Bear 数据库中获取全部标签信息
• 📖 读取笔记内容，以便进行分析和总结
• ✏️ 创建笔记，并返回笔记的 ID
• 📝 添加文本，向现有笔记中添加文本内容
• ✅ 测试设置，通过全面的状态检查来测试设置情况

⚠️ 当前限制与使用指南

浏览器窗口行为

预期情况：由于 Bear 的回调系统，在搜索/标签操作期间可能会短暂出现浏览器窗口。

• 窗口会自动最小化并移至屏幕外
• 大多数情况下，会在 1 - 2 秒内自动关闭
• 若窗口持续存在，可手动关闭
• 焦点会自动返回到你原来的窗口

搜索可靠性

成功率：约 80 - 90% 的搜索能可靠工作

• 偶尔会出现超时情况（限制为 20 秒）
• 简单术语比复杂查询效果更好
• 若搜索超时，可重试一次
• 单个单词通常比短语更可靠

最佳实践

✅ 推荐用法：

Search my Bear notes for "project"
Get all my Bear tags
Create a note titled "Meeting Notes" with today's agenda
Add "Action item: Follow up" to my "Weekly Review" note

⚠️ 若出现问题：

• 超时：等待片刻，然后重试相同的搜索
• 浏览器窗口：若窗口未自动关闭，可手动关闭
• 无结果：尝试更简单/更宽泛的搜索词
• 设置问题：使用 check_bear_setup 进行诊断

📦 安装指南

1. 克隆仓库：

git clone https://github.com/philgetzen/bear-mcp.git
cd bear-mcp

2. 安装依赖：

npm install

3. 构建项目：

npm run build

在 Claude Desktop 中进行配置

将服务器添加到你的 Claude Desktop 配置文件中：

macOS

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

{
  "mcpServers": {
    "bear": {
      "command": "node",
      "args": ["/path/to/bear-mcp/dist/index.js"]
    }
  }
}

Windows

编辑 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "bear": {
      "command": "node",
      "args": ["C:\\path\\to\\bear-mcp\\dist\\index.js"]
    }
  }
}

Bear 配置

必需设置：

1. 启用 x-callback-url：

   • 打开 Bear → 设置（⌘,）
   • 转到“高级”选项卡
   • 启用“允许 x-callback-url”

2. 生成 API 令牌（用于搜索和标签）：

   • 打开 Bear → 帮助 → 高级 → API 令牌
   • 点击“复制令牌”
   • 在 Claude 中，使用 set_bear_token 并输入你的令牌

💻 使用示例

基础用法

设置和测试

Check my Bear setup and show me what's available

可靠操作（始终有效）

Create a new Bear note titled "Project Ideas" with content about machine learning

Add "## Next Steps\n- Review documentation\n- Schedule follow-up" to my "Weekly Review" note

搜索操作（通常有效）

Search my Bear notes for "machine learning" and show me what you find

Get all my Bear tags and help me organize them

内容分析（搜索成功时）

Search for "meeting notes" then help me identify common action items across all results

Find notes tagged with "work" and summarize the main topics

🔧 技术细节

HTTP 回调系统

服务器使用 HTTP 回调（端口 51234）从 Bear 接收数据：

• Bear 通过 URL 回调发送搜索结果和标签数据
• 由于此回调机制，浏览器窗口会短暂出现
• Bear 响应设置 20 秒超时
• 针对常见故障有自动重试机制

性能特点

• 快速操作：笔记创建、文本添加（约 1 - 2 秒）
• 中等操作：单个笔记检索（约 3 - 5 秒）
• 较慢操作：搜索、标签列表（约 5 - 15 秒）
• 超时阈值：最长等待 20 秒

可用工具

故障排除

"Search failed: Callback timeout"

• 正常情况：约 10 - 20% 的时间会出现
• 解决方案：等待 5 - 10 秒，然后重试相同的搜索
• 提示：尝试更简单的搜索词（单个单词效果更好）

"No token configured"

获取你的令牌：Bear → 帮助 → 高级 → API 令牌 → 复制令牌，然后使用 set_bear_token

"Bear not found"

确保 Bear 已安装，并且至少打开过一次。

浏览器窗口出现

• 预期行为，由于 Bear 的回调系统
• 窗口会自动最小化并移至屏幕外
• 若窗口持续存在，可手动关闭
• 焦点会自动返回你原来的窗口

无搜索结果

• 检查搜索词：确保该词存在于你的笔记中
• 验证令牌：使用 check_bear_setup 进行测试
• 尝试更宽泛的术语：单个单词通常比短语更有效
• 直接检查 Bear：验证内容是否存在于 Bear 应用中

开发

若要以开发模式运行：

npm run dev

若要测试服务器：

npm run build
node dist/index.js

版本历史

• v4.0.2：增强了浏览器窗口处理能力，设置 20 秒超时
• v4.0.1：提高了回调可靠性，优化了错误消息
• v4.0.0：通过回调系统恢复了完整功能
• v3.1.0：仅包含文档的版本（功能有限）

要求

• Node.js 18 或更高版本
• 系统中安装了 Bear 应用
• 安装了 Claude Desktop 应用
• macOS（Bear 仅支持 macOS）

📄 许可证

本项目采用 MIT 许可证。