thebrain

thebrain-mcp

ローカル API を利用して構築された、TheBrain 15 用の MCP サーバーです。

エージェントが脳内で意味に基づく操作を行えるようにします。意味で検索し、グラフの近傍を読み取り、分解した素材を、全体がつながった構造として脳内に書き込めます。API の単なる複製ではなく、48 個のエンドポイントに対してツールは 19 個です。

目的は「このテキストを保存する」ことではありません。エージェントに記事を渡すと、それを読み、意味ごとに分解し、それぞれを既存のグラフのどこに配置するか、何とリンクするか、各ノートに何を書くかを判断できるようにすることです。

npm では thebrain-mcp-server として公開されています。npm では、より短い名前が無関係な既存パッケージに近すぎると判断されるためです。インストール後のコマンドは引き続き thebrain-mcp です。

必要条件

• TheBrain 15 が起動しており、ローカル API が有効になっていること
• Node.js 22 以降
• API キー：Settings → User → Local API Key

インストール

Claude Code

claude mcp add thebrain -e THEBRAIN_API_KEY=your-key -- npx -y thebrain-mcp-server

設定ファイルを使用するクライアント

{
  "mcpServers": {
    "thebrain": {
      "command": "npx",
      "args": ["-y", "thebrain-mcp-server"],
      "env": { "THEBRAIN_API_KEY": "your-key" }
    }
  }
}

セマンティック検索

TheBrain の検索は先頭一致です。OT で OTGP が見つかりますが、同義語やタイプミスでは何も見つかりません。意味に基づいて検索するため、サーバーはローカルのベクトルインデックスを構築します。

埋め込みパッケージはインストールに含まれません。サイズは約 380 MB で、初回実行時にはモデル自体にも 113 MB 必要です。必要な場合に限り、別途インストールしてください。

npm install -g @huggingface/transformers

その後、クライアントから brain_index を action: "rebuild" で実行します。思考が 10,000 件ある脳のインデックス作成には約 1 分かかります。以降の実行では、変更された部分のみが再計算されます。

このパッケージがなくてもサーバーは動作します。 brain_search は、エージェントから渡された同義語で複数の先頭一致検索を行う方法に切り替え、検索精度が下がることを明示します。

すべてローカルで処理されます。脳の内容も検索クエリも、外部に送信されません。

設定

変数	デフォルト	用途
THEBRAIN_API_KEY	—	必須
THEBRAIN_BASE_URL	http://localhost:11522、次に :8001	ローカル API アドレス
THEBRAIN_DATA_DIR	~/.thebrain-mcp	インデックスの保存場所
THEBRAIN_ALLOW_DESTRUCTIVE	0	思考とリンクの削除を許可
THEBRAIN_EMBEDDING_MODEL	Xenova/multilingual-e5-small	埋め込みモデル
THEBRAIN_EMBEDDING_DTYPE	q8	重みの精度
THEBRAIN_TIMEOUT_MS	30000	API リクエストのタイムアウト

モデルまたは精度を変更すると、既存のインデックスは使用できなくなります。その場合、サーバーがその旨を伝え、再構築を求めます。

通常、THEBRAIN_BASE_URL を設定する必要はありません。TheBrain のアップデートでローカル API のポートが 8001 から 11522 に変更されたため、サーバーは新しいポートを試してから古いポートにフォールバックします。TheBrain が別の場所で待ち受けている場合にのみ、この変数を設定してください。Settings に表示されるエンドポイント（http://localhost:11522/api/）をそのまま指定できます。

ツール

読み取り

ツール	機能
brain_list	脳の一覧、開いている脳、インデックスの準備状況
brain_get_thought	思考、その別名、グラフ、ノートを1回の呼び出しで取得
brain_search	意味で検索
brain_traverse	グラフを数ホップたどる
brain_list_types_and_tags	脳の語彙
brain_recent_changes	変更内容を平易な言葉で表示
brain_index	インデックスの状態、構築、更新

書き込み

ツール	機能
brain_create_thought	ノート、タイプ、タグ、別名を含む思考を作成
brain_update_thought	名前、ラベル、タイプ、色を更新し、別名を追加・削除
brain_set_note / brain_append_note	ノートを置き換え、または追記
brain_link	2つの思考をラベル付きで接続し、replace を使うと、それらを結ぶリンクを別の種類に変更
brain_unlink	人による確認を経てリンクを削除
brain_tag	タグを付ける、または外す
brain_create_type_or_tag	タイプまたはタグを新規作成。同名のタグが脳にすでにある場合は、新たに作成せず既存のものを返す
brain_attach_url	リンクを重複なしで添付
brain_activate	ユーザーの画面で思考を開く
brain_delete_thought	人による確認を経て削除
brain_ingest	1回の呼び出しで構造全体を書き込む

brain_ingest

脳に内容を取り込むための主要なツールです。エージェントは素材を思考に分割し、一時的な識別子を使ってそれらをつなぎ合わせ、全体を1回の呼び出しで登録します。

{
  "brainId": "…",
  "thoughts": [
    { "tempId": "art",   "name": "Article on RAG", "parent": "<uuid of an existing thought>" },
    { "tempId": "embed", "name": "Embeddings", "parent": "art", "note": "…" },
    { "tempId": "store", "name": "Vector store", "parent": "art" }
  ],
  "links": [
    { "from": "embed", "to": "store", "name": "is written into" }
  ]
}

入力内の思考の順序は問いません。依存関係は自動的に解決されます。同じプランを2回実行しても重複は生じず、すでに存在する思考のノートはそのまま保持されます。プランのノートはノートがまだない場合にのみ書き込まれ、どのノートが保持されたかは結果に示されます。不正なプラン（循環参照や存在しない項目への参照）は、最初の書き込みより前に拒否されます。

スキル

サーバーが提供するのは、決定論的な操作の仕組みです。意味をどれほど細かく分割するか、既存の項目にいつ関連付けるか、何をノートに記載するかといった方法論は、Claude Code のスキルとして別に用意されています。スキルは通常の Markdown ファイルなので、サーバーを再構築しなくても、自分の作業方法に合わせて調整できます。

スキル	実行される場面
thebrain-ingest	「この記事を脳に入れて」「これを分解して記録して」
thebrain-research	「X について何を知っている？」「これについて、もう話したことがある？」
thebrain-organize	「脳を整理して」「重複を見つけて」
thebrain-digest	「今週追加したものは？」「最近取り組んでいたことは？」

シンボリックリンクとしてインストールすると、リポジトリ内での編集がすぐに反映されます。

mkdir -p ~/.claude/skills
for d in skills/*/; do
  ln -sfn "$PWD/$d" ~/.claude/skills/"$(basename "$d")"
done

リポジトリへのリンクを使いたくない場合は、コピーしてください。単一のプロジェクトで使う場合は、~/.claude/skills の代わりに、プロジェクトのルートにある .claude/skills を使用します。

スキルはセッションの開始時に読み込まれます。すでに実行中のセッションでは再起動が必要です（claude --continue を使うと会話が引き継がれます）。

削除

思考（brain_delete_thought）とリンク（brain_unlink）の削除です。デフォルトでは無効です。THEBRAIN_ALLOW_DESTRUCTIVE=1 を設定しても、人による承認が必要です。クライアントが対応していれば確認フォームを使い、そうでなければ明示的なフラグを付けて2回目の呼び出しを行います。この判断をエージェントがあなたに代わって行うことはできません。

開発

npm install
npm test                 # unit tests, no live TheBrain needed
npm run build

稼働中の API に対するコントラクトテスト：

THEBRAIN_API_KEY=… npm test                                  # read-only
THEBRAIN_API_KEY=… THEBRAIN_TEST_BRAIN_ID=<uuid> npm test    # + writes

書き込みテストには、専用の使い捨ての脳が必要です。思考が500件を超える脳には変更を加えないようになっています。脳を必要とする読み取り専用テストも同じ脳を読み取り、脳がない場合はスキップされます。どのテストも、別の脳を読み取ることはありません。

ドキュメント

• ARCHITECTURE.md — サーバーの構築方法とその理由：レイヤーの境界、メカニズムとポリシーの分離、エラーに対する考え方、セマンティックレイヤー、そして各判断の背景にある理由。
• docs/api-map.md — ローカル API の動作（文書化されていない部分を含む）。実際に稼働しているインスタンスで検証し、測定結果も記載しています。
• docs/stack-evaluation.md — 数値を交えた、TypeScript を選んだ理由。
• CONTRIBUTING.md — このプロジェクトへの取り組み方。

サポート

thebrain-mcp は、空き時間を使って開発・保守されています。ワークフローに役立つと感じたら、GitHub でスポンサーになることで支援できます。一度限り、または毎月の支援をお選びいただけます。

ライセンス

MIT