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 許可證。