Bear MCP

🚀 Bear MCP Server

このサーバーは、BearノートアプリとClaude Desktopを統合するためのMCP（Model Context Protocol）サーバーです。Claudeが直接あなたのBearノートを読み取り、作成、検索できるようになります。

🚀 クイックスタート

このサーバーを使うことで、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

トラブルシューティング

"Search failed: Callback timeout"

• 正常な現象: 約10 - 20%の確率で発生します。
• 解決策: 5 - 10秒待ってから同じ検索を再試行してください。
• ヒント: より単純な検索用語を試してみてください（単語の方がうまく機能します）。

"No token configured"

トークンを取得します: Bear → ヘルプ → 詳細 → APIトークン → トークンをコピーし、set_bear_tokenを使用して設定します。

"Bear not found"

Bearがインストールされており、少なくとも1回開かれていることを確認してください。

ブラウザウィンドウが表示される

• 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