neuro-mcp

臨床・研究におけるEEGワークフロー全体を操作するためのインターフェースを、AI エージェントに提供します。信号処理とソースイメージング（MNE-Python経由）、永続的なデータセットおよび EHR ストア（Postgres + BIDS）、そして NeuroII のウェブ可視化が含まれます。

コンセプト

flowchart LR
    Clinician(["🩺 Clinician"])
    Researcher(["🔬 Researcher"])
    Agent[["🤖 AI Agent"]]
    Server(("neuro-mcp<br/>FastMCP · 54 tools"))

    Clinician -- talks to --> Agent
    Researcher -- talks to --> Agent
    Agent -- MCP --> Server

    Server --> Processing["Processing &amp; Source Imaging<br/>MNE-Python + ESI"]
    Server --> Data["Data &amp; EHR Store<br/>Postgres + BIDS<br/>versioned &amp; audited"]
    Server --> NeuroII["NeuroII<br/>Web Visualization"]

    classDef proc fill:#4f8cff,stroke:#2f5fbf,color:#fff
    classDef data fill:#2fb380,stroke:#1c7a55,color:#fff
    classDef viz fill:#b06fe0,stroke:#7c3fae,color:#fff
    class Processing proc
    class Data data
    class NeuroII viz

臨床医や研究者がツールを直接呼び出すことはありません。自然な英語でエージェントに話しかけると、エージェントが裏側で neuro-mcp の54個のツールを操作します。実際の一連の流れについては、チュートリアルをご覧ください。

アクターとワークフロー

• 臨床医 — 記録を確認し、注釈を追加・編集し、EHRを修正（診断や所見を記録、値を修正）してから、承認します。
• 研究者 — データセットを検索し、BIDSにインポートし、MNE処理とソースイメージングを実行します。
• エージェント — ツール呼び出しを通じて、上記の作業を調整します。

臨床安全性モデル（EHRと注釈）

EHRレコードと注釈はバージョン管理され、上書きや完全削除はされません。

• 修正 = 監査可能な新バージョンの作成。 amend_ehr_record / update_annotation は新しいバージョンを追加し、以前のバージョンはステータス amended で保持されます。そのため、臨床医はEHRを変更できます。現在の表示は更新されますが、元の記録と作成者は保持されます。
• 撤回 = ソフト無効化。 void_ehr_record / void_annotation はステータスを entered-in-error に設定します。レコードは履歴に残ります。
• すべての変更は監査されます（audit_log：アクター、操作、変更前／変更後）。
• 変更を行うツールには明示的な actor を渡すため、作成者が記録されます。（認証／RBACによる適用はv0.2で予定されています。フィールドと監査履歴はすでに用意されています。）

各ツールは、操作の outcome フィールド（created/amended/voided/…）を返します。これはレコードの臨床的な status とは別のもので、両者が混同されることはありません。

ツール（54）

• 処理（load_neuro、filter_neuro、resample_neuro、set_montage、 set_reference、detect_bad_channels、run_ica/apply_ica、find_events、 epoch_neuro、compute_psd、compute_erp、time_frequency、plot_*）と ソースイメージング／ESI（fetch_template_head … extract_label_timecourses）。
• データ／EHR：register_subject、get_subject、add_ehr_record、 amend_ehr_record、get_ehr_history、void_ehr_record；import_recording、 register_dataset、query_datasets、list_recordings；add_annotation、 update_annotation、list_annotations、void_annotation；get_audit_log。
• neuroii：neuroii_push_recording、neuroii_create_viz_session、 neuroii_pull_annotations。
• neuroiiの可視化（スタンドアロンのインタラクティブHTML、Plotly）：visualize_timeseries （スクロール、振幅ボタン、注釈マーカーを備えた、複数チャンネルEEGの積み重ね表示）、visualize_averaging （時間スライダーで操作できるERPバタフライ表示と頭皮トポマップ）、visualize_esi （ソース推定のROI時系列と、各時点のアクティベーションバー）。

インストール

conda create -n neuro-mcp python=3.11 -y   # or any Python >=3.10 env
conda activate neuro-mcp
pip install neuro-mcp              # core, from PyPI
pip install "neuro-mcp[postgres]"  # + PostgreSQL driver (LGPL-3.0)
pip install "neuro-mcp[viz3d]"     # + 3D source rendering (PySide6, LGPL-3.0)

neuro-mcp 自体を開発する場合は、リポジトリをクローンし、上記の行の代わりに pip install -e . を使用してください。Claude Code／Codex CLI／Claude Desktop の 登録を含む、初期状態から使いこなすまでの手順については、 インストールを参照してください。

設定（環境変数）

変数	デフォルト	用途
DATABASE_URL	sqlite:///~/.neuro-mcp/neuro_mcp.db	保存先。運用環境：postgresql+psycopg://user:pass@host/db
BIDS_ROOT	~/.neuro-mcp/bids	ディスク上の BIDS 記録ツリーのルート
NEUROII_API_URL	(未設定)	neuroii のベース URL。未設定の場合、ツールは文書化された契約を返します
NEUROII_API_TOKEN	(未設定)	neuroii 用の任意のベアラートークン
NEURO_MCP_HOME	~/.neuro-mcp	SQLite と BIDS のデフォルト設定に使うベースディレクトリ

デフォルト設定（SQLite と一時的な BIDS ディレクトリ）はセットアップ不要で動作します。複数ユーザー／臨床環境でのデプロイでは、DATABASE_URL を Postgres に設定してください。

MCP ホストで実行／登録する

python -m neuro_mcp     # stdio transport

{
  "mcpServers": {
    "neuro-analysis": {
      "command": "/path/to/envs/neuro-mcp/bin/python",
      "args": ["-m", "neuro_mcp"],
      "env": { "DATABASE_URL": "sqlite:////data/neuro_mcp.db", "BIDS_ROOT": "/data/bids" }
    }
  }
}

neuroii のウェブ可視化

3 つのツールは、NEUROII の主なビューを単独で動作するインタラクティブな HTMLファイルに移植します（Plotly を埋め込み、サーバー不要でオフライン動作）。それぞれ .html のパスを返し、操作はクライアント側で実行されます。

• visualize_timeseries（RawView）— ページ移動（⏮ ◀ ▶ ⏭）、ページ長入力欄、スクロールによる振幅のズーム、グリッドの切り替え、ラベル付きマーカー線として描画される記録アノテーション（切り替え可能）を備えた、MNE スタイルのチャンネル積層表示です。
• visualize_averaging（EvokedView）— 平均化した ERP をチャンネル積層表示し、緑色の時間カーソルと頭皮トポマップを表示します。時間スライダーで両方を移動できるほか、サマリーサイドバー（nave／ピーク／tmin／tmax）もあります。
• visualize_esi（EsiView）— ボリュームソース推定（fsaverage テンプレート）を、3 つの直交する MRI スライス（矢状断／冠状断／軸位断）上にキャンバス描画します。黒・青・白・赤の賦活オーバーレイ、十字線、左右と MNI 座標のラベルを備え、各フレームのピークに合わせて断面が再センタリングされます。下部には、赤い現在時刻カーソルと青い半ピークマーカーを備えた ERP バタフライプロットがあります。コントロール：時間スライダー、全体／フレームのカラーマップスケール切り替え、マスク閾値スライダー。NEUROII のビューを忠実に移植したもので、エポック（epoch_neuro と set_montage）が必要です。

visualize_averaging(session_id="s") -> {"out_path": ".../averaging_s.html", ...}

neuroii との統合（グリーンフィールド）

neuroii との統合はまだ接続されていません。ツールは想定される REST 契約（neuro_mcp/neuroii/client.py を参照）を定義して返します。NEUROII_API_URL が設定されるまでは、neuroii アプリが実装するための固定された接続先として、{"status": "not_configured", "contract": {…}} を返します（POST /api/v1/recordings、POST /api/v1/viz-sessions、GET /api/v1/recordings/{id}/annotations）。

テスト

python testing/verify.py     # in-memory MCP client, temp SQLite + BIDS, synthetic EEG

名称変更の整合性、処理コア、臨床医向け EHR／アノテーションの全ライフサイクル（追加 → 修正 → 履歴 → 無効化、および監査）、neuroii スタブを対象とします。Postgres を使ったフルスタック実行には、testing/docker-compose.yml を使用してください。

ライセンス

neuro-mcp は BSD-3-Clause で、サードパーティのソースコードはバンドルしていません。必要な依存関係はすべて許容的ライセンス（BSD／MIT／Apache-2.0／PSF）です。任意の追加機能には、それぞれ独自の条件があります（psycopg（LGPL-3.0）、PySide6（GPL の PyQt6 ではなく LGPL-3.0 を選択））。帰属表示とコンプライアンスに関する注記の全文は、NOTICE にあります。

ライセンス

BSD-3-Clause — LICENSE を参照してください。