Ephys

ephys-mcp

MCP サーバーです。LLM が皮質内（スパイクレベル）のブレイン・コンピューター・インターフェース記録を解析できます。解析対象は、信号品質、スパイク検出、発火率、カーソル速度のデコーディングです。

既存の BCI MCP サーバーは頭皮 EEG を対象としています。このサーバーは、多チャンネルのインプラントが生成する種類のデータを対象としており、メーカーが API を公開した際にライブデバイスのバックエンドを追加できるよう、読み取り専用のアダプター契約を定義しています。

研究および教育用ソフトウェアです。医療機器ではありません。臨床使用を目的としていません。 Neuralink Corp. またはその他のインプラントメーカーとは提携しておらず、承認も受けていません。

出力例

組み込みの合成データソース（32 ユニット、300 秒、シード 2）から、サーバー独自のプロットツールで生成した図です。

到達方向でグループ化した plot_psth：各方向の集団発火率（166 試行の平均 ± SEM）と、その下にベースラインからの変化を示すユニット別・時間別ヒートマップ	fit_decoder(kind="kalman") の後に実行した plot_decoding：保留された 10 秒間のウィンドウで、デコード結果と実際のカーソル速度を比較。R² は x 方向で 0.90、y 方向で 0.83

ステータス

v0.5。予定されていた機能はすべて実装済みです。ローカルの NWB ファイル、ローカルのブロードバンド WAV 記録、ライブの Lab Streaming Layer ストリーム、DANDI Archive からのストリーミング、正解データ付きの合成運動皮質データソース、スパイク検出、品質指標、リッジデコーダーとカルマンデコーダー、試行に整列した PSTH、スパイクソーティング、セッション間（FALCON 形式）評価、潜在因子モデル（GPFA、PCA）、プローブのジオメトリ、図をサポートしています。ツールは 24 種類です。バグ報告や機能リクエストは GitHub Issues へお寄せください。

インストールと実行

uv が必要です。インストール手順はありません。uvx ephys-mcp を実行すると、パッケージを取得して stdio でサーバーを起動します。

Claude Code：

claude mcp add ephys -- uvx ephys-mcp

Claude Desktop（claude_desktop_config.json）：

{ "mcpServers": { "ephys": { "command": "uvx", "args": ["ephys-mcp"] } } }

チェックアウトから実行する場合は、代わりに uv run ephys-mcp を使うか、上記の設定で uv --directory /path/to/ephys-mcp run ephys-mcp を使ってください。

HTTP トランスポート

リモートクライアントやホスト型エージェント向けには、stdio の代わりにストリーミング可能な HTTP で提供します。

EPHYS_MCP_TOKEN='a-long-random-secret' uvx ephys-mcp --http --host 0.0.0.0 --port 8000

その場合、すべてのリクエストに Authorization: Bearer <token> を含める必要があります。トークンなしでループバック以外のアドレスにバインドしようとすると、サーバーは拒否します。また、トークンは 16 文字以上である必要があります。プライベートネットワークの外部に公開する前に、TLS を適用してください（リバースプロキシを使用）。適用しない場合、トークンは暗号化されずに送信されます。ループバックではトークンは任意のため、ephys-mcp --http だけで http://127.0.0.1:8000/mcp が提供され、ローカルでテストできます。

実データの場合は、次のように尋ねてください。「DANDI で小規模な運動皮質データセットを見つけて開き、手の速度をどの程度うまくデコードできるか教えてください。」 オフラインの場合は、次のように尋ねてください。「合成セッションを開き、信号品質を確認して、カルマンデコーダーを学習し、デコードしたウィンドウを表示してください。」

データソース

ソース	開くデータ
synthetic	カーソル速度に合わせて調整されたシミュレーションユニット。広帯域信号とグラウンドトゥルースを含みます
nwb	ローカルの .nwb ファイル（params.path）
wav_dir	ローカルの広帯域 WAV（params.path）：モノラルクリップのフォルダー（各クリップ1チャンネル）、または1つのマルチチャンネルファイル
lsl	ローカルネットワーク上のライブ Lab Streaming Layer 広帯域ストリーム。信号の最新 buffer_s 秒分を保持します。uvx --with 'ephys-mcp[lsl]' ephys-mcp が必要です
dandi	HTTP Range リクエストで DANDI Archive からストリーミングされる NWB ファイル。ミラーは作成されません
n1_stub	未実装です。lsl と同じ基盤上でライブインプラントアダプターを記述する方法を示します

データセットのライセンスと引用情報はアーカイブから取得され、open_session によって返されるため、モデルはデータの出典を明記できます。多くのデータセットは試行中のみ記録されます。サーバーは記録された区間（recorded_fraction）を追跡し、無音として扱うのではなく、その区間外を発火率とデコーディングから除外します。

WAV サンプルには物理単位がないため、uv_per_count を渡さない場合、振幅は ADC カウントで報告されます。振幅の結果にはすべて単位が明記されます。フォルダー内のクリップは別々の記録であるため、サーバーはチャンネル間のタイミングに意味がないことを示します。WAV から得られるスパイク時刻は閾値交差であり、ソート済みユニットではありません。

参考結果。いずれも最先端の手法ではなく、シンプルな因果的線形ベースラインです。

• MC_Maze_Small（DANDI 000140、142ユニット、最後の20%をホールドアウト、50 ms ビン）：手の速度について、リッジの R² は 0.50、カルマンの R² は 0.34 です。
• FALCON H1（DANDI 000954、人間の7自由度速度、176チャンネル、20 ms ビン、eval_mask）：最初の学習対象日に対して学習したリッジモデルの R² は、その日の minival で 0.43、1週間後には 0.07、ホールドアウト日では0未満です。この劣化こそがベンチマークの要点です。カルマンフィルターは、このスクリプト化されたキャリブレーションデータには適していません。FALCON の公式テストラベルは非公開のため、これらはリーダーボードのスコアではありません。

デコーダーのハイパーパラメーター（リッジ強度、カルマン用の神経信号のリード）は、学習分割内のブロック化交差検証で選択します。ビンサイズにかかわらず、リッジでは0.5秒分のスパイクカウント履歴を使用します。

GPFA は論文の方程式に基づき numpy と scipy で実装されています（負荷量、オフセット、ノイズ、因子ごとの時間スケールを EM で推定。ディープラーニングへの依存はありません）。100試行でも数秒で実行できます。真の潜在変数が2次元のカーソル速度であるシミュレーターでは、速度を R² 0.95 で説明する2つの支配的な因子を見つけます（PCA：0.68）。MC_Maze_Small では、運動皮質で知られている、運動開始付近で回転する集団軌道を示します。LFADS クラスのモデルは対象外です。数分間の学習実行とディープラーニングスタックが必要なためです。

ツール

ツール	目的
list_sources	ソースの種類とそのパラメーター
search_datasets	DANDIを検索するか、厳選された皮質内データセットの一覧を表示します
list_dataset_files	DANDIデータセットのライセンス、引用情報、NWBファイル
list_lsl_streams	ネットワーク上で利用可能なLSLストリーム
get_stream_status	ライブセッションのバッファー範囲、データ到着の有無、欠落数
open_session / close_session	セッションのライフサイクル
get_session_info	チャンネル、サンプリングレート、行動信号、ライセンス、引用情報
get_signal_quality	ノイズ、SNR、故障チャンネル／ノイズの多いチャンネル
detect_spikes	閾値交差。正解データがある場合は適合率／再現率も算出します
sort_spikes	spikeinterface（sort extra）を使ってブロードバンドのウィンドウ内のスパイクを分類します。プローブのジオメトリがわかっている場合は使用し、その後のセッションでは分類済みユニットを使用します
set_probe_geometry	ファイルにないセッションの接点位置を指定します。ユタ、グリッド、リニア、テトロードの配置、または明示的な座標に対応します
get_probe	チャンネルごとの接点位置と脳領域ラベル
plot_probe	図：アレイマップ、発火率で色分けされた接点、接点ごとの分類済みユニット
get_firing_rates	集団発火率の概要
fit_decoder	リッジまたはカルマン。保留データでスコアを算出し、ハイパーパラメーターは学習用分割の内部で選択します
decode_window	ウィンドウ内のデコード結果と正解値のプレビュー
evaluate_cross_session	あるセッションで学習し、変更せずに別のセッションでスコアを算出します。デコーダーは後日のセッションでも機能するでしょうか？FALCONのeval_maskを尊重します
get_psth	試行イベントに合わせて発火を揃えます。任意で試行列ごとにグループ化するか、一部のユニットに限定できます
fit_latent_factors	試行に揃えた活動に対するGPFA（Yu et al. 2009）またはPCA：単一試行の潜在軌跡、因子ごとの分散、時間スケール、上位因子が速度信号をどの程度説明するかを算出します
plot_latent_factors	図：時間経過に伴う上位3因子、因子1／因子2の状態空間、因子ごとの分散
plot_psth	図：グループごとのSEM付きPSTHと、ベースラインからの変化を示すユニット×時間のヒートマップ
plot_raster	図：スパイクラスター。記録されていない区間は網掛けで表示します
plot_decoding	図：デコードされた行動と実際の行動を表示します。次元ごとに1つのパネルを使用します

リソース：ephys://sessions。プロンプト：analyze_session、falcon_evaluate。

ツールは概要を返し、生の配列は返さないため、結果はモデルのコンテキストに収まります。

オプションの追加機能

追加機能	追加されるもの	インストール
lsl	lslライブソース	uvx --with 'ephys-mcp[lsl]' ephys-mcp
sort	spikeinterface組み込みのソーター（spykingcircus2、tridesclous2）によるsort_spikes。依存関係は約330 MB	uvx --with 'ephys-mcp[sort]' ephys-mcp

スパイク分類では、ファイルの電極テーブルまたはset_probe_geometryからセッションのプローブジオメトリを使用するため、100 µm未満の間隔にある接点はまとめて分類されます。これは高密度プローブで重要です。シミュレーションによる20 µm間隔の層状プローブでは、正しいジオメトリを使って分類すると実際の12個のユニットが見つかりますが、接点を独立したものとして扱うと15個と報告され、隣接する接点で同じユニットを重複して数えます。ジオメトリがない場合、チャンネルは互いに大きく離して配置され、独立した電極として扱われます。シミュレーターでは、spykingcircus2は再現率0.95超ですべてのユニットを検出します。

脳領域ラベルは、存在する場合はNWB電極テーブルから取得されます（MC_MazeではPMdとM1が報告されます）。get_probeはチャンネルごとのラベルを一覧表示するため、分析対象を絞り込む際にunits引数で領域を指定できます。これまでに試したDANDIデータセットには接点座標が保存されていないため、アレイ配置の指定にはset_probe_geometryを使います。

プロットツールはPNGをインラインで返すため、視覚機能を備えたモデルで図を読み取れます。また、~/.cache/ephys-mcp/plotsにも保存されます（EPHYS_MCP_OUTPUT_DIRで変更可能）。図には色覚特性の違いを考慮して色の識別性を確認したカテゴリ別パレットを使い、色だけに頼らず識別できるよう直接ラベルを付けています。

設計ルール

• 読み取り専用です。 NeuralSource コントラクトには、書き込み、刺激、設定を行うメソッドはありません。別途安全性を設計しない限り、追加することはありません。
• デフォルトではローカルです。 stdio トランスポートを使用し、テレメトリーはありません。HTTP はオプトインで、トークンによる制御が必要です。神経データは機微な情報です。
• サードパーティのデータは同梱しません。 DATA_LICENSES.md を参照してください。

ソースアダプターの作成

記録データの場合は、ephys_mcp.sources.base.NeuralSource をサブクラス化します（info、read_raw、spike_times、behavior）。ライブデバイスの場合は、ephys_mcp.sources.live.RingBufferSource をサブクラス化し、リーダースレッドから push(samples) を呼び出します。sources/lsl.py は約 60 行の完全な例で、sources/n1_stub.py にはインプラントアダプターに追加で必要な項目が記載されています。クラスを ephys_mcp/sources/__init__.py に登録してください。

ライブセッションでは、時刻は開始からの秒数で報告され、読み取れるのは直近のバッファーのみです。そのため、t_start_s と duration_s は進んでいきます。

開発

uv run pytest              # offline
uv run pytest -m network   # also streams a real file from DANDI
uv run ruff check .

引用

CITATION.cff を参照してください。GitHub の「このリポジトリを引用」ボタンでは、このファイルが使用されます。分析するデータセットは個別に引用してください。get_session_info は、それぞれのデータセットの引用情報を返します。

ライセンス

CC0 1.0 Universal。著者は、法律で認められる範囲で、著作権および関連するすべての権利を放棄します。用途を問わず使用でき、帰属表示は不要です。CC0 は特許権または商標権を付与するものではありません。