Ephys

ephys-mcp

一个 MCP 服务，可让大模型分析皮层内（尖峰级）脑机接口记录：信号质量、尖峰检测、放电率和光标速度解码。

现有的 BCI MCP 服务面向头皮 EEG。本服务面向高通道数植入设备所生成的数据，并定义了只读适配器契约，以便在供应商发布 API 后接入实时设备后端。

研究和教育软件。不是医疗器械。不可用于临床。 与 Neuralink Corp. 或任何其他植入设备制造商无关联，也未获得其认可。

输出示例

图表由内置合成数据源（32 个单元、300 s、种子 2）生成，使用服务器自带的绘图工具制作。

按到达方向分组的 plot_psth：上方为每个方向的群体放电率（166 次试验的均值 ± SEM），下方为单元×时间基线变化热图	fit_decoder(kind="kalman") 后运行 plot_decoding：在留出的 10 s 时间窗口中，将解码结果与实际光标速度进行对比，R² 为 0.90（x）和 0.83（y）

状态

v0.5。计划中的功能集已全部完成：本地 NWB 文件、本地宽带 WAV 录音、实时 Lab Streaming Layer 流、从 DANDI Archive 流式读取数据、带真实值的合成运动皮层数据源、尖峰检测、质量指标、岭回归和卡尔曼解码器、试次对齐的 PSTH、尖峰排序、跨会话（FALCON 风格）评估、潜变量模型（GPFA、PCA）、探针几何信息和图表。共 24 个工具。Bug 报告和功能请求请提交至 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 传输

对于远程客户端或托管 Agent，可使用可流式传输的 HTTP，而非 stdio：

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）：包含多个单声道片段的文件夹（每个片段一个通道），或一个多通道文件
lsl	本地网络上的实时Lab Streaming Layer宽带流；保留最近 buffer_s 秒的信号。需要 uvx --with 'ephys-mcp[lsl]' ephys-mcp
dandi	通过 HTTP 范围请求从 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 时间箱）：手部速度的 ridge R² 为 0.50，Kalman R² 为 0.34。
• FALCON H1（DANDI 000954，人类 7 自由度速度，176 个通道，20 ms 时间箱，eval_mask）：在首个训练日上训练的 ridge，在该日的 minival 上得分为 R² 0.43，一周后为 0.07，在留出的日期上则低于零。这种衰减正是此基准要展示的情况；Kalman 滤波器不适用于这类脚本生成的校准数据。FALCON 的官方测试标签为私有数据，因此这些结果并非排行榜成绩。

解码器超参数（ridge 强度、Kalman 的神经信号超前量）通过训练划分内的分块交叉验证选取。无论时间箱大小如何，ridge 历史窗口均为 0.5 s 的尖峰计数。

GPFA 根据论文中的公式，使用 numpy 和 scipy 实现（对载荷、偏移量、噪声和每个因子的时间尺度进行 EM；不依赖深度学习），在一百个试次上只需数秒即可运行。在真实潜变量为二维光标速度的模拟器上，它找到两个主导因子，二者对速度的解释度为 R² 0.95（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	为文件中没有几何信息的会话提供触点位置：Utah、网格、线性、四极管布局或显式坐标
get_probe	各通道的触点位置和脑区标签
plot_probe	图表：阵列图、按放电率着色的触点、每个触点上的排序单元
get_firing_rates	群体放电率摘要
fit_decoder	Ridge 或 Kalman；在留出数据上评分；在训练划分内选择超参数
decode_window	某个窗口的解码值与真实值预览
evaluate_cross_session	在一个会话上拟合，在其他会话上不作更改地评分：解码器能否适用于之后的某一天？遵循 FALCON 的 eval_mask
get_psth	与试验事件对齐的放电；可按试验列分组，或限制为部分单元
fit_latent_factors	对试验对齐活动进行 GPFA（Yu et al. 2009）或 PCA：单试验潜在轨迹、各因子的方差、时间尺度，以及顶部因子对速度信号的解释效果
plot_latent_factors	图表：随时间变化的前三个因子、因子 1/因子 2 状态空间，以及各因子的方差
plot_psth	图表：各组的 PSTH 及 SEM，上方为相对基线变化的单元-时间热图
plot_raster	图表：脉冲栅格图，并用阴影标出未记录时段
plot_decoding	图表：解码行为与实际行为的对比，每个维度一个面板

资源：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 不授予专利权或商标权。