🚀 Bear MCP Server
Bear MCP Server 是一个 MCP（模型上下文协议）服务器，用于将 Bear 笔记应用与 Claude Desktop 集成。通过该服务器，Claude 可以直接读取、创建和搜索你的 Bear 笔记，为笔记管理和使用带来极大便利。
🚀 快速开始
本服务器可让你轻松地将 Bear 笔记应用与 Claude Desktop 集成，实现笔记的读取、创建和搜索等功能。
✨ 主要特性 (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进行诊断。
可用工具
| 工具 | 功能 | 可靠性 | 说明 |
|---|---|---|---|
create_note |
创建新笔记 | ✅ 优秀 | 始终有效，返回 ID |
add_text |
向笔记中添加文本 | ✅ 优秀 | 可靠的文本添加功能 |
check_bear_setup |
测试配置 | ✅ 优秀 | 诊断工具 |
search_notes |
搜索笔记 | ⚠️ 良好 | 约 80 - 90% 的成功率，可能会超时 |
get_tags |
获取所有标签 | ⚠️ 良好 | 通常有效，可能会出现短暂的弹出窗口 |
get_note |
检索笔记内容 | ⚠️ 良好 | 在使用有效 ID 时工作良好 |
📦 安装指南
- 克隆仓库：
git clone https://github.com/philgetzen/bear-mcp.git
cd bear-mcp
- 安装依赖：
npm install
- 构建项目：
npm run build
🔧 在 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 配置
必需设置：
-
启用 x-callback-url：
- 打开 Bear → 设置 (⌘,)
- 转到 "高级" 选项卡
- 启用 "允许 x-callback-url"
-
生成 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
🔧 故障排除
"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 应用中。
🔧 技术细节
HTTP 回调系统
服务器使用 HTTP 回调（端口 51234）从 Bear 接收数据：
- Bear 通过 URL 回调发送搜索结果和标签数据。
- 由于此回调机制，浏览器窗口会短暂出现。
- Bear 响应的超时时间为 20 秒。
- 对于常见故障有自动重试机制。
性能特征
- 快速操作：笔记创建、文本添加（约 1 - 2 秒）。
- 中等操作：单个笔记检索（约 3 - 5 秒）。
- 较慢操作：搜索、标签列表（约 5 - 15 秒）。
- 超时阈值：最长等待时间为 20 秒。
开发
开发模式运行
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 许可证。