🧠 TheBrain MCP サーバー
AIアシスタントがTheBrainの知識管理システムと連携できるようにするMCP(Model Context Protocol)サーバー。TheBrain APIへの包括的なアクセスを提供し、自然言語によるTheBrainの強力な知識管理機能との対話に焦点を当てています。
🔧 MCPサーバーとは?
MCP(Model Context Protocol) は、ClaudeのようなAIアシスタントを外部ツールやサービスに接続するための標準規格です。自然言語とソフトウェアAPIをつなぐ「翻訳者」のようなものだと考えてください。
仕組み
あなた → Claude → MCPサーバー → TheBrain API → あなたのBrain
- あなたが話す: 「3つのフェーズを持つプロジェクトを作成して」
- Claudeが理解する: 達成したいことを把握
- MCPサーバーが変換する: 具体的なTheBrain API呼び出しに変換
- TheBrain APIが作成する: 思考(Thought)と接続を生成
- あなたのBrainが更新される: 新しい構造が反映
優れているのは、技術的な詳細を知る必要がまったくないことです。ただ普通の言葉で説明するだけです!
🚀 実際に動作する機能
✅ コア機能(動作中)
- コンテンツ管理: 思考とノートの作成・更新・削除
- ファイル添付: 思考に画像、PDF、ドキュメントをアップロード
- Web参照: タイトル自動抽出付きのURL添付
- リッチノート: 埋め込みコンテンツを含む完全なMarkdownサポート
- リレーションシップマッピング: 意味のある関係で思考を接続
- 検索: 思考・ノート・添付ファイルを横断する全文検索
- Brain管理: 複数のBrainをシームレスに切り替え
- 自然言語インターフェース: やりたいことを説明すれば、Claudeが詳細を処理
❌ 現在の問題と制限事項
🚨 重大なビジュアルスタイリング問題
最大の制限: APIが成功レスポンスを返すにもかかわらず、ビジュアルプロパティが実際には適用されません。
- ❌ 思考の色: APIは色を受け付けるが、TheBrain上には表示されない
- ❌ リンクの色: 同様の問題 - 受け付けられるが適用されない
- ❌ リンクの太さ: APIは成功を報告するが、太さは変化しない
- ❌ ビジュアルフォーマット: すべてのビジュアルスタイリング機能が現在機能していない
🐛 その他の既知の問題
- 断続的な接続問題: 操作成功後に「Field required」エラーが発生
- 長いノートの制限: 非常に長いMarkdownコンテンツで問題発生(10k文字以下に抑えること)
- ファイルパスの感度: 絶対ファイルパスが必要。相対パスは失敗する可能性がある
- 接続タイミング: MCP初期化の競合状態による散発的な失敗
- メモリ制約: 大きなファイル添付はタイムアウトを引き起こす可能性がある
- 検索の制限: 複雑なクエリは不完全な結果を返すことがある
📋 API依存関係と制約
- シングルユーザー操作: リアルタイムコラボレーション機能なし
- 一括操作なし: 大規模データセットの効率的なインポート/エクスポート不可
- API接続が必須: オフラインモードは利用不可
- TheBrain APIの制限: 既存のAPI機能に縛られる
- 認証が必要: 有効なTheBrain APIキーが必須
🛠 現在の回避策
ビジュアルスタイリングが修正されるまで、以下の代替手段を使用してください:
- 絵文字で区別: 色の代わりに 🟢🟡🔴⚪🔵 を使用
- 説明的な名前: 色付き思考の代わりに「🔴 緊急タスク」
- リッチなMarkdownノート: ノート内のフォーマットで視覚的な整理を実現
- 階層構造: 親子関係に頼って整理
📦 インストール
- このリポジトリをクローン:
git clone https://github.com/redmorestudio/thebrain-mcp.git
cd thebrain-mcp
- 依存関係をインストール:
npm install
- APIキーを含む
.env ファイルを作成:
THEBRAIN_API_KEY=your_api_key_here
THEBRAIN_DEFAULT_BRAIN_ID=optional_default_brain_id
⚙️ 設定
Claude Desktop の場合
Claude Desktopの設定に以下を追加:
{
"mcpServers": {
"thebrain": {
"command": "node",
"args": ["/absolute/path/to/thebrain-mcp/index.js"],
"env": {
"THEBRAIN_API_KEY": "your_api_key_here"
}
}
}
}
⚠️ 重要: 設定およびファイル添付には絶対ファイルパスを使用してください。
🐞 デバッグとトラブルシューティング
よくある問題と解決策
「Field required」エラー:
- Claude Desktopを再起動する
.env ファイルに正しいAPIキーがあるか確認する
- 常に最初にアクティブなBrainを設定する: 「Set my active brain to [name]」
ファイルアップロードの失敗:
- 絶対ファイルパスを使用:
/Users/username/Documents/file.pdf
- ファイルの権限と存在を確認する
- ファイルサイズを適切に保つ(< 50MB)
長いノートの問題:
- ノートは10,000文字以下に抑える
- 大きなコンテンツは複数の思考に分割する
- 長文ドキュメントには添付ファイルを使用する
デバッグモード:
VERBOSE=true node index.js
🧰 利用可能なツール(25以上の機能)
Brain管理
list_brains - 利用可能なすべてのBrainを一覧表示
get_brain - Brainの詳細を取得
set_active_brain - 操作対象のアクティブBrainを設定
get_brain_stats - 包括的なBrain統計を取得
思考(Thought)操作
create_thought - 思考を作成(ビジュアルプロパティは機能しない)
get_thought - 思考の詳細を取得
update_thought - 思考のプロパティを更新
delete_thought - 思考を削除
search_thoughts - Brain全体を検索
get_thought_graph - すべての接続を含む思考を取得
get_types - すべての思考タイプを一覧表示
get_tags - すべてのタグを一覧表示
リンク操作
create_link - 思考間のリンクを作成(スタイリングは機能しない)
update_link - リンクのプロパティを変更
get_link - リンクの詳細を取得
delete_link - リンクを削除
添付ファイル操作
add_file_attachment - 思考にファイル/画像を添付 ✅
add_url_attachment - Web URLを添付 ✅
get_attachment - 添付ファイルのメタデータを取得
get_attachment_content - 添付ファイルの内容をダウンロード
delete_attachment - 添付ファイルを削除
list_attachments - 思考の添付ファイルを一覧表示
ノート操作
get_note - Markdown/HTML/テキストでノートを取得 ✅
create_or_update_note - ノートを作成または更新 ✅
append_to_note - 既存のノートにコンテンツを追加 ✅
高度な機能
get_modifications - Brainの変更履歴を表示
💻 使用例(実際に動作するもの)
プロジェクト整理
あなた: 「『キッチンリノベーション』というプロジェクトを作成して」
Claude: 中心となるプロジェクト思考を作成
あなた: 「計画、解体、設置のフェーズを追加して」
Claude: 各フェーズに接続されたサブ思考を作成
あなた: 「業者の見積もりを計画フェーズに添付して」
Claude: 計画思考にファイルをアップロード
あなた: 「プロジェクトにスケジュールの詳細ノートを追加して」
Claude: あなたのスケジュールを含むリッチなMarkdownノートを作成
リサーチと知識管理
あなた: 「持続可能エネルギーの研究トピックを作成して」
Claude: メインの研究思考を設定
あなた: 「太陽光、風力、水力のサブトピックを追加して」
Claude: 整理された思考階層を作成
あなた: 「関連する論文とWeb記事を添付して」
Claude: ファイルとURLの添付を追加
あなた: 「効率に関連するすべてを検索して」
Claude: 関連するすべての思考とコンテンツを検索
🔮 ロードマップと今後の開発
当面の優先事項(v1.2.0)
- 🚨 ビジュアルスタイリングの修正: 色/太さが適用されない理由を調査
- 🔧 接続の安定性: MCPのタイミング/競合状態の問題を解決
- 📝 長いノートのサポート: 大規模なMarkdownコンテンツのより良い処理
- 🛡️ エラーハンドリング: より優雅な失敗と回復
今後の機能強化
- 一括操作: 大規模な整理のため
- 強化されたテンプレート: 一般的なワークフロー用
- パフォーマンス最適化: 複雑なBrain向け
- オフライン機能: およびキャッシング
🏗 技術アーキテクチャ
このサーバーの特徴
- 自然言語インターフェース: 技術的な知識は不要
- 完全なAPIカバレッジ: すべてのTheBrain操作を網羅する25以上のツール
- 堅牢なエラーハンドリング: 優雅な失敗と明確なエラーメッセージ
- モジュラー設計: クリーンで保守可能なコードアーキテクチャ
- 本番環境対応: 適切なロギング、テスト、ドキュメント
現在のステータス
- バージョン: 1.1.0(2025年6月)
- コア機能: ✅ 完成・動作中
- ビジュアルプロパティ: ❌ 調査が必要な重大な問題
- 安定性: 🟡 断続的な接続問題はあるが、概ね安定
🤝 コントリビューション
コントリビューションを歓迎します!特に支援が必要な分野:
- ビジュアルスタイリングの調査: なぜ色/太さが適用されないのか?
- 接続の安定性: MCPの競合状態のデバッグ
- パフォーマンス最適化: 大規模Brainの処理
- ドキュメント: より多くの使用例とチュートリアル
IssueやPull Requestをお気軽に送信してください。
📄 ライセンス
MIT License - 詳細は LICENSE ファイルを参照してください。
💬 サポート
- TheBrain APIドキュメント: https://api.bra.in
- Issue・バグ報告: https://github.com/redmorestudio/thebrain-mcp/issues
- 質問: GitHubディスカッションを開いてください
⚠️ 現在の推奨事項
このサーバーは、自然言語インタラクションを伴う コンテンツ管理と整理 に使用してください。ビジュアルスタイリング機能が修正されるまでは、それらに依存しないでください。コア機能は堅牢であり、会話を通じてTheBrainのコンテンツを管理するのに非常に役立ちます!