brain-mcp

アイコン・デザイン: wenmeiZhou （iStock）

Markdown で構成された PARA 構造のセカンドブレイン・ボールト（Obsidian 互換）を、読み取り専用ツール群と、制約付きの単一書き込みツール（capture。00-inbox/ に新しいノートを作成するだけ）として公開する MCP サーバーです。Docker コンテナとして動作し、streamable-HTTP 経由で Claude Code、opencode、その他の MCP クライアントから利用されます。

完全な動作仕様は、このリポジトリ（または任意の場所）にある brain-mcp-spec.md を参照してください。設計上の判断の「理由」が必要な場合に役立ちます。

CONVENTIONS.md パーサーに関する注意

brain_structure() は、type/status/domain の各 enum を、ボールトの 90-meta/CONVENTIONS.md からハードコードせずに動的に読み取ります（src/brain_mcp/vault.py の _extract_enum_values を参照）。実際のボールトのファイルで直接検証済みです。そのファイルでは、3 つの enum が ## Enums 見出しの下に太字のインラインラベルとして記載されています（**type:** \note`、`project`、...）。各 enum に個別の小見出しはありません。そのため、_extract_enum_values はまずその形式を試します（ラベルの段落内に限定されるため、下の散文にある無関係なバッククォート付きの単語（例：「domainは主要なクエリ軸です...」）を拾いません）。次に、enum の文書化方法が異なるボールト向けに、見出しベースのヒューリスティックにフォールバックします。後でCONVENTIONS.md` の Enums セクションを再構成する場合は、このパーサーを再確認してください。3 つのフィールドすべてについて空でない値リストを解析できない場合、サーバーは起動時に大きなエラーを出して停止し、不正なデフォルトにフォールバックすることはありません。

uid 形式: この検証に使用したボールトの CONVENTIONS.md には現在、自己矛盾があります。フロントマターの例は UUIDv4 を示し、その 2 行下の散文は実際の形式が YYYYMMDD-HHmm（同時刻の衝突時は文字を追加）であると述べ、ディスク上の実際のノートは 3 つの異なる方式を使用しています（1 つのインボックスノートでは UUIDv4、メタドキュメントでは 00000000-000N のセンチネル、_index.md ファイルでは YYYYMMDD-000N の連番カウンター）。capture() は UUIDv4 を生成します。これは元の仕様が要求したもので、現在のコードと一致し、read_note の短いプレフィックス検索（8 文字以上）を意味のあるものに保ちます。低エントロピーの日付ベース ID では、同じ日のすべてのものが同じプレフィックスを共有するため、意味がありません。独自の CONVENTIONS.md が異なる uid 方式を文書化している場合、それはボールト側で調整する価値があります。このサーバーが自動的に行うことではありません。

Related MCP server: Obsidian MCP Server

要件

• ボールトの 90-meta/CONVENTIONS.md に記載されている PARA 構造とフロントマタースキーマ。

• Unraid ボックス上の Docker（または Docker Compose）、または開発用の Python 3.12 + uv。

• PATH 上の ripgrep（コンテナイメージに同梱。ローカル開発では個別にインストール）。

設定

すべての設定は環境変数を介して行われます。特定のボールト（パス、名前、トークン）に関する情報はハードコードされていないため、同じイメージが複数の兄弟ボールトを別々のコンテナとして提供できます。

.env.example を .env にコピーし、BRAIN_NAME、BRAIN_VAULT_PATH（ボールトへのホストパス）、BRAIN_TOKEN（ランダムなシークレット — openssl rand -hex 32 で十分）を入力してから Compose を実行してください。

ローカル開発

uv sync --dev          # or: python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
uv run pytest          # or: .venv/bin/python -m pytest

テストは tests/conftest.py で構築された合成フィクスチャボールトに対してのみ実行されます。実際のデータに対しては実行されません。

実際の（またはスクラッチの）ボールトディレクトリに対してサーバーをローカルで実行するには:

export BRAIN_ROOT=/path/to/vault
export BRAIN_NAME=personal
export BRAIN_TOKEN=dev-token
uv run brain-mcp

Unraid での実行

cp .env.example .env   # fill in BRAIN_NAME, BRAIN_VAULT_PATH, BRAIN_TOKEN
docker compose up -d --build   # or: docker compose pull && docker compose up -d
curl http://<unraid-host>:3100/health

--build はこのチェックアウトからビルドします。pull は代わりに GHCR から同じイメージを取得します（下記の「Unraid アプリとしてインストール」を参照）。どちらでもローカルに ghcr.io/sipho102/brain-mcp:latest タグが生成されます。

compose ファイルは BRAIN_VAULT_PATH を読み取り専用でマウントし、その上に 00-inbox/ だけを読み書き可能で再マウントします:

volumes:
  - ${BRAIN_VAULT_PATH}:/vault:ro
  - ${BRAIN_VAULT_PATH}/00-inbox:/vault/00-inbox:rw

これは意図的で重要な設計です。書き込みパスにバグがあっても、Python コードが何をしていると思っていても、インボックス以外には触れられません。単一の読み書きマウントに簡略化しないでください。

代わりに Unraid アプリとしてインストール

Unraid の Docker タブから他のアプリと同様に管理したい場合（.env を編集する代わりのフォーム、その後の Start/Stop/Update ボタン）は、unraid/brain-mcp.xml にテンプレートがあります。.github/workflows/publish.yml は、このリポジトリのイメージをビルドし、main へのプッシュごとに GHCR（ghcr.io/sipho102/brain-mcp:latest）に公開します。テンプレートはそれを直接取得するため、Unraid ボックスでのクローンやビルドは一切不要です。

テンプレートを Unraid で利用できるようにするには:

• 推奨 — Docker タブで Add Container をクリックし、このリポジトリの生のテンプレート URL をテンプレートフィールドに直接貼り付けます: https://raw.githubusercontent.com/sipho102/brain-mcp/main/unraid/brain-mcp.xml この方法では Unraid のローカルテンプレートフォルダに何も書き込まれないため、後で競合する可能性のある余分なファイルが残りません。代替方法の注意点については下記を参照してください。

• または、SSH で Unraid のローカルテンプレートフォルダにコピーします:

  curl -o /boot/config/plugins/dockerMan/templates-user/brain-mcp.xml \
    https://raw.githubusercontent.com/sipho102/brain-mcp/main/unraid/brain-mcp.xml

  その後、Docker → Add Container → template ドロップダウン に表示されます。ただし、Add Container の直後に、コンテナが存在するようになったらこのファイルを削除するという注意点を参照してください。

どちらの方法でも、ボールトパス、インボックスパス（<vault path>/00-inbox である必要があります。テンプレートは自動的に導出できません）、インスタンス名、ベアラートークン用のフォームが表示されます。その他はすべて「詳細ビュー」で適切なデフォルト値が事前入力されます。

上記のローカルコピー方法を使用した場合は、コンテナが追加されたらそのシードファイルを削除してください:

rm /boot/config/plugins/dockerMan/templates-user/brain-mcp.xml

Add Container で Apply をクリックすると、Unraid は実際の値を持つ 2 番目 のファイル（ダウンロードした空白のファイルの隣に my-brain-mcp.xml）を保存します。両方が同じコンテナ名を宣言します。2 つのテンプレートがその名前を主張している場合、Update は保存されたものではなく空白のオリジナルからコンテナを再作成し、BRAIN_NAME/BRAIN_TOKEN/パスを消去して起動不能にする可能性があります。 my-brain-mcp.xml が存在するようになったら（ls /boot/config/plugins/dockerMan/templates-user/ で確認）、シードファイルは役目を終えているので、曖昧さをなくすために削除してください。その後 Update をクリックすると、保存された設定を使用して ghcr.io/sipho102/brain-mcp:latest の最新版が期待どおりに取得されます。

2 つ目のボールトを提供する

1 つのコンテナは 1 つのボールトを提供します。docker-compose.yml には意図的にマルチボールトのサービスリストはなく、Unraid テンプレートにもマルチボールトのフォームはありません。上記の Unraid アプリのパスでは、同じテンプレートから Add Container を別の名前/パス/トークン/ポートで再度実行するだけです。Compose のパスでは、このデプロイディレクトリ（または docker-compose.yml + .env だけ）を別の場所にコピーし、そのコピーの .env に別の BRAIN_NAME、BRAIN_VAULT_PATH、BRAIN_TOKEN、PORT を入力し、そこからも docker compose up -d --build を実行します。同じイメージ（brain-mcp:latest）、独立したコンテナです。

コンテナのユーザー / 権限

コンテナは非 root ユーザー（デフォルトで UID:GID 99:100、Unraid の nobody:users）として実行されます。共有で異なる所有権が必要な場合は、.env の BRAIN_UID/BRAIN_GID でビルド時に上書きできます。このユーザーはホスト共有の 00-inbox/ への書き込みアクセス権を持っている必要があります。

クライアントの接続

Claude Code

claude mcp add --transport http --scope user brain \
  http://<unraid-host>:3100/mcp \
  --header "Authorization: Bearer <token>"

セッションで /mcp と入力すると、6 つのツールすべてが一覧表示されるはずです。

既知の問題: Claude Code には、--header で設定したヘッダーがセッション確立中に送信されず、同じトークンで curl が正常に動作しても 401 が発生するという再発性のバグがあります。これに遭遇した場合は、headers オブジェクトを JSON 設定に直接書き込んでください（~/.claude/mcp_servers.json または関連するスコープファイル）:

{
  "mcpServers": {
    "brain": {
      "type": "http",
      "url": "http://<unraid-host>:3100/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

（type は JSON 設定で http のエイリアスとして streamable-http も受け入れます。）

opencode

opencode はデフォルトでリモート MCP サーバーに対して OAuth ディスカバリを試行し、明示的に無効にしない限り静的ベアラートークンを無視します:

{
  "mcp": {
    "brain": {
      "type": "remote",
      "url": "http://<unraid-host>:3100/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

oauth: false がないと、opencode はヘッダーを使用する代わりに OAuth ハンドシェイクを試行（および失敗）します。

ヘッダーフィールドがまったくないクライアント

一部の MCP クライアント UI は、名前、トランスポート、URL のみを受け付け、カスタム Authorization ヘッダーを設定する方法がありません。そのような場合は、代わりにトークンを URL に含めてください:

http://<unraid-host>:3100/mcp?token=<token>

サーバーはまず Authorization ヘッダーをチェックし、?token= クエリパラメータにフォールバックするため、上記のヘッダーベースの設定と同じ場所で機能します。これに依存する前に知っておくべきこと: URL 内のトークンは、ヘッダーよりも多くの場所に残る可能性があります。クライアントの保存設定、URL が直接開かれた場合のブラウザ履歴、ターミナルに貼り付けた場合のシェル履歴などです。アクセスログはここでは問題になりません（uvicorn のアクセスログはオフです）が、URL 自体をシークレットを保持するものとして扱ってください。トークン自体と同じように。

ツール

6 つのツール。意図的に小さく保たれています（ツールスキーマはクライアントのコンテキストを消費します）:

• brain_structure() — オリエンテーション: PARA フォルダとカウント、CONVENTIONS.md からのライブ enum、フロントマタースキーマ、完全なコンベンションテキスト、ノート数。セッションで最初に呼び出してください。

• search_notes(query, domain, type, status, para, tag, limit) — フロントマターフィルタリング付きの全文検索（ripgrep）。メタデータと約 200 文字のスニペットを返します。本文全体は返しません。

• read_note(identifier) — ボールト相対パス、完全な uid、または曖昧でない uid プレフィックス（8 文字以上）による完全なノート。

• list_notes(para, domain, status, type, limit) — メタデータのみのブラウジング。コンテンツ検索はありません。

• get_backlinks(identifier) — このノートにリンクしているノートと、そのコンテキスト行。

• capture(title, body, domain, tags, source, links) — 唯一の書き込み: 00-inbox/ に新しいノートを作成します。上書きは決して行わず、インボックス外には一切触れません。

意図的に行わないこと

セマンティック検索/埋め込みはありません。00-inbox/ 外への書き込みアクセスはありません。Obsidian Local REST API への依存はありません（ファイルシステムを直接読み取ります）。paperless-ngx のドキュメント取得はありません（フロントマターからドキュメント ID を返し、クライアントが別の paperless MCP サーバーに連鎖させます）。git 操作はありません。理由については brain-mcp-spec.md §2 を参照してください。