MNE-MCP

MNE-MCP

English | 简体中文

一个 Model Context Protocol（MCP） 服务，让 AI 助手能够直接通过对话使用 MNE-Python，分析人类神经生理数据——EEG、MEG、sEEG、ECoG 和 fNIRS。

用自然语言描述你的分析需求——MNE-MCP 会加载你的记录，运行 MNE 工作流（滤波、ICA、分段、ERP/ERF 平均、时频分析，以及通过代码进行源级分析），保存图表并解释结果。

支持 Claude Code、Codex、PsyClaw 和 opencode。搭配内置的 Agent 技能使用——mne-analyst、mne-mcp-guard，以及一套审慎的分析套件（mne-methodology-critic + 各类别技能），实现可靠、可归档的工作流。

---

为什么要为 MNE-Python 使用 MCP？

MNE 分析具有状态性且依赖可视化的特点——这与一次性统计批处理不同：

• 加载一次 Raw 记录后，依次进行滤波 → 重新参考 → 拟合 ICA → 分段 → 平均 → 时频分析，每一步都会修改大型内存对象。MNE-MCP 会保留一个持久会话，因此各步骤之间无需重新加载记录。
• 每项决策都需要观察（PSD、传感器图、ICA 成分、ERP）。每个绘图工具都会保存一张助手可以读取和解读的 PNG 图片。
• MNE 提供了庞大的 Python API。MNE-MCP 提供 41 个结构化工具，涵盖常见工作流和高级分析（源定位、连接性、解码），还提供 mne_run_code 这一备用入口，可在同一实时会话中访问整个 MNE API。
• 默认设置（电源频率、蒙太奇、滤波带、拒绝阈值、ICA 设置、分段窗口、目录、超时）可通过交互式 mne-mcp configure 向导由用户配置。

---

要求

• Python 3.12+（不设软件包版本上限；完整测试基线：3.12）
• Git
• Claude Code、Codex、PsyClaw、opencode 或其他 MCP 客户端

跨平台：与封闭式引擎不同，MNE-Python 采用纯 Python 编写，因此分析工具可在 Windows、macOS 和 Linux 上运行。

---

安装

想了解单独提供的原生 C++ 预览版？请参阅 MNE-CPP MCP 安装与功能。 它现已包含明确的原生运行时设置和配套技能注册； 但它不能替代此处介绍的 MNE-Python 分析后端。

使用 Agent 安装

将以下内容发送给有终端访问权限的编码 Agent：

按照 https://github.com/Exekiel179/MNE-MCP/blob/v0.4.4/INSTALL_AGENT.md，在我现有的 MNE 环境中安装 MNE-MCP 和所有配套技能，配置我当前使用的客户端，并验证安装结果。

Agent 会检查环境，在需要时安装缺少的 MNE/核心库，安装轻量级接口和全部 14 个技能，并注册所选客户端。需要重启客户端。请参阅安装指南，了解环境检查和验证步骤。

手动安装

激活现有的 Python 3.12+ MNE 环境，然后安装轻量级接口：

python -m pip install mne-mcp
mne-mcp setup

安装后会创建 mne-mcp 命令（Windows 上为 mne-mcp.exe）。 python -m mne_mcp setup 仍可作为等效的诊断调用方式。

发布版本下载：最新版本。 对于下载的源代码归档文件，解压后在该目录中运行 python -m pip install .。 安装程序默认配置全部四个客户端及其技能。若只配置 PsyClaw， 请使用 mne-mcp setup --clients psyclaw；也支持 claude、codex 和 opencode （以逗号分隔）。安装后请重启客户端；PsyClaw 支持 /reload。 MNE 和科学计算库由用户自行管理；安装此软件包不会安装这些依赖项。 有关依赖项和故障排除，请参阅安装说明。

配置

修复或重新配置

若要更新现有安装，请运行 python -m pip install --upgrade mne-mcp。 在同一个 MNE 环境中运行 mne-mcp setup --clients codex。 安装程序会注册该确切的解释器，并为所选客户端安装随附的技能。 更新前会备份现有配置和技能文件。

PsyClaw 验证

PsyClaw 注册会写入 ~/.psyclaw/mcp/mne.json；全部 14 个技能及其参考文件 会写入 ~/.psyclaw/skills。安装程序会检查真实的 MCP 握手、工具发现和 mne_check_status，并再次检查已保存的 PsyClaw 命令。

mne-mcp verify --client psyclaw

此操作会检查已保存的命令，不会修改注册信息。connected 和 mne_available 是彼此独立的：即使未安装 MNE，轻量级服务也可以连接。 /reload 后，请让 PsyClaw 列出服务器 mne 的工具并调用 mne_check_status。 项目中的 .psyclaw/mcp/*.json 条目若具有相同 ID，会覆盖用户配置。 安装检查不会声称你当前已运行的聊天会话已重新加载。

环境变量（可选的 .env）

MNE_MCP_TIMEOUT=300          # per-operation timeout (s); raise for ICA / TFR / large files
MNE_MCP_RESULTS_DIR=...      # where figures + exported objects are saved
MNE_MCP_DATA_DIR=...         # default directory mne_list_files scans

配置分析默认值（交互式向导）

设置结构化工具的回退默认值，包括电源线频率（50/60 Hz）、默认 电极布局、滤波频带、EEG 拒绝阈值、ICA 方法/成分数、分段时间窗口、目录 和超时时间：

mne-mcp configure            # interactive prompts (Enter keeps current value)
mne-mcp configure --show     # print current defaults
mne-mcp configure --reset    # back to built-in defaults
mne-mcp configure --set line_freq=60 default_montage=biosemi64 reject_eeg_uv=120   # non-interactive

默认值会保存到 ~/.mne-mcp/config.json（可通过 MNE_MCP_CONFIG 覆盖路径）。运行时优先级为： 环境变量 > 配置文件 > 内置默认值。在会话中使用 mne_get_config 工具查看当前生效的配置。重启 MCP 服务后更改才会生效。

技能

安装程序会将全部 14 个技能及其参考文件安装到所选客户端的技能目录中。 Claude 还会获得 methodology-review 子 Agent。其他客户端使用 methodology-critic 技能。 更新软件包后请重新运行安装程序。

---

使用方法

只需描述你想做什么：

加载 sub-01_raw.fif，看一下功率谱

对 raw 做 1–40 Hz 带通、50 Hz 陷波，然后跑 ICA 去眼电

Epoch around the 'target' trigger, -0.2 to 0.8 s, average it, and show the ERP topomaps at 100/200/300 ms

助手将会：

1. 检查功能（mne_check_status）
2. 将录制数据加载到持久会话中
3. 逐步运行处理流程，并以 PNG 格式显示图表
4. 用通俗语言解读每项结果
5. 将图表和对应的 MNE 代码归档到 mne_result/

---

输出

每个绘图工具都会将 PNG 保存到结果目录并返回其路径：

> Figure: `C:\...\mne-mcp\results\psd_01.png`

安装 mne-analyst 技能后，结果及生成结果的确切 MNE 代码会归档到 工作目录中的 mne_result/（按序号命名），从而确保分析过程完全可复现。

---

可用工具（41 个）

状态与会话（7 个）

mne_check_status · mne_session_info · mne_describe · mne_get_info · mne_reset_session · mne_run_code · mne_get_config

数据 IO（2 个）

mne_list_files · mne_load_raw

预处理（7 个）

mne_filter · mne_resample · mne_crop · mne_set_montage · mne_set_reference · mne_mark_bad_channels · mne_interpolate_bads

可视化（3 个）

mne_plot_psd · mne_plot_raw · mne_plot_sensors

ICA（4）

mne_fit_ica · mne_plot_ica_components · mne_plot_ica_sources · mne_apply_ica

事件 / Epoch / ERP（7）

mne_find_events · mne_events_from_annotations · mne_make_epochs · mne_plot_epochs_image · mne_average_evoked · mne_plot_evoked · mne_plot_topomap

时频分析（2）

mne_compute_tfr（Morlet/多窗，周期数可自定义，ITC，试次功率，基线）· mne_tfr_morlet

高级分析（8）

mne_decode（MVPA）· mne_connectivity · mne_compute_connectivity（频带、配对、估计器）· mne_compute_noise_cov · mne_make_forward · mne_apply_inverse · mne_plot_source_estimate

mne_decoding_group_test 提供参与者层面的 max-T 或经聚类校正的推断。 解码报告会分别呈现数值证据、方法、解读、局限性，以及需要经过科学审查的结果草稿。代码逃生口不等同于对每个 MNE API 都有经过验证的结构化覆盖。

导出（1）

mne_save

仍未覆盖的内容——BIDS、自定义统计、波束形成器、autoreject——可通过同一实时会话中的 mne_run_code 实现。完整的参数详情请参阅 TOOLS_REFERENCE.md。高级依赖项会按功能检查，不会随附打包。

---

开发

# Compile check
python -m compileall src/mne_mcp

# Run tests
pytest

# CLI commands
mne-mcp status            # Check environment
mne-mcp setup --clients codex # Register in Codex + install skills

---

许可证

MIT——请参阅 LICENSE

文档

• 项目介绍 / 简介：docs/INTRODUCTION.md · .docx
• 安装指南：docs/INSTALL.md · .docx
• 使用指南：docs/USAGE.md · .docx
• 快速入门：QUICK_START.md
• 工具参考：TOOLS_REFERENCE.md

链接

• MNE-Python：https://mne.tools/
• MCP 协议：https://modelcontextprotocol.io