MNE-MCP

CI License: MIT Python 3.10+ MCP

English | 简体中文

A Model Context Protocol (MCP) server that gives AI assistants direct, conversational access to MNE-Python for analyzing human neurophysiology data — EEG, MEG, sEEG, ECoG, and fNIRS.

Describe your analysis in plain language — MNE-MCP loads your recording, runs the MNE pipeline (filtering, ICA, epoching, ERP/ERF averaging, time-frequency, source-level work via code), saves the figures, and explains the results.

Works in Claude Code and opencode (any MCP-capable client). Pairs with bundled Agent Skills — mne-analyst, mne-mcp-guard, plus a skeptical analysis suite (mne-methodology-critic + per-category skills) for reliable, archived workflows.

---

Why an MCP for MNE-Python?

MNE analysis is stateful and visual — unlike a one-shot statistics batch job:

• You load a Raw recording once, then filter → re-reference → fit ICA → epoch → average → time-frequency, each step mutating large in-memory objects. MNE-MCP keeps one persistent session so recordings never get re-loaded between steps.
• Every decision is driven by looking (PSD, sensor maps, ICA components, ERPs). Every plotting tool saves a PNG the assistant can read and interpret.
• MNE is a huge pure-Python API. MNE-MCP gives you 38 structured tools spanning the common pipeline and advanced analysis (source localization, connectivity, decoding), plus an mne_run_code escape hatch that reaches the entire MNE API in the same live session.
• Defaults (line frequency, montage, filter band, rejection threshold, ICA settings, epoch window, dirs, timeout) are user-configurable via an interactive mne-mcp configure wizard.

---

Requirements

• Python 3.10+
• MNE-Python ≥ 1.6 — provisioned on demand (see Lightweight by default); install it up front with mne-mcp[analysis] if you prefer
• scikit-learn for ICA (in the ica / full extras, or mne-mcp install-backend)
• Claude Code (or any MCP client) with MCP support

Cross-platform: unlike a closed engine, MNE-Python is pure Python, so analysis tools work on Windows, macOS, and Linux.

---

Quick Install

git clone https://github.com/Exekiel179/MNE-MCP.git
cd MNE-MCP

# 1. Install (pulls in mne, numpy, scipy, matplotlib, scikit-learn for ICA)
pip install -e ".[ica]"

# 2. Register in your MCP client(s) — Claude Code, Codex, opencode — and install skills
mne-mcp setup

# 3. Restart your client

Or run the one-shot installer (creates the venv, installs, verifies, registers, installs skills):

pwsh -File scripts\install.ps1     # Windows

bash scripts/install.sh            # macOS / Linux

See QUICK_START.md for a guided first session, or docs/INSTALL.md for the full guide.

One command does everything: mne-mcp setup registers the mne server in Claude Code, Codex, and opencode (whichever you use) and installs the companion skills. Narrow it with --clients claude,codex. The mne_* tools require one client restart afterwards (MCP servers load at startup).

Run via uvx / pipx (standard MCP — recommended)

mne-mcp is published on PyPI, so the most portable path is the standard MCP launcher — no clone, no setup. Add this to your client config (~/.claude.json for Claude Code, claude_desktop_config.json for Claude Desktop):

{ "mcpServers": { "mne": { "command": "uvx", "args": ["--from", "mne-mcp[ica]", "mne-mcp", "serve", "--transport", "stdio"] } } }

uvx (from uv) fetches and runs mne-mcp on demand. The [ica] extra pulls in scikit-learn so ICA works out of the box; swap it for mne-mcp[full] to also get the advanced tools (source localization, connectivity, decoding, BIDS). Because MNE pulls in a large scientific stack, a persistent install is usually snappier than re-resolving each run:

pipx install "mne-mcp[ica]"        # or: uv tool install "mne-mcp[ica]"  (use [full] for advanced tools)

then set the config command to mne-mcp with args: ["serve", "--transport", "stdio"]. The source install above remains the path for development.

No uv? Bootstrap pipx with plain Python, then install and register in one go:

python -m pip install --user pipx
python -m pipx ensurepath          # reopen your terminal so `pipx` lands on PATH
pipx install mne-mcp               # lightweight; provision the backend on demand
mne-mcp setup                      # register in clients + install skills
mne-mcp install-backend            # add MNE + ICA (or let the mne_install_backend tool do it)

Skills are bundled in the package (since 0.2.2). A PyPI install carries the skill suite and the mne-methodology-critic agent, so one extra command installs them — mne-mcp setup (after pipx/ uv tool install) or uvx mne-mcp setup. No clone required.

Lightweight by default — on-demand backend

Since 0.3.0 the package itself is tiny: a bare pip install mne-mcp / pipx install mne-mcp pulls in only the MCP protocol layer (mcp, fastmcp, pydantic, python-dotenv), so it installs in seconds. The heavy scientific stack (MNE-Python + numpy/scipy/matplotlib/pandas, and scikit-learn for ICA) is provisioned the first time an analysis needs it:

• In a session, just ask — when a tool reports the backend is missing, call the mne_install_backend tool (or it is offered by mne_check_status). It pip installs into the server's own environment and becomes usable without a client restart.
• From a terminal: mne-mcp install-backend (add --profile full for source localization / connectivity / decoding / BIDS).

pipx install mne-mcp            # tiny, instant
mne-mcp install-backend        # add MNE + ICA when you're ready (or let the tool do it)

Prefer everything up front? Install an extra instead: mne-mcp[analysis] (MNE core), [ica] (+ scikit-learn), or [full] (+ advanced tools). For ephemeral uvx runs, pin the extra in the config (--from mne-mcp[ica], as above) since an uvx environment is discarded between runs, so an on-demand install would not persist.

---

Configuration

Auto-configure (recommended)

mne-mcp setup                          # Claude Code + Codex + opencode, plus skills
mne-mcp setup --clients claude,codex   # only specific clients
mne-mcp configure-claude               # Claude Code only (subset of setup)

setup registers the mne server in each client and installs the skills, writing a timestamped backup of any file it touches:

Client	Config file	Key
Claude Code	~/.claude.json	mcpServers.mne
OpenAI Codex CLI	~/.codex/config.toml	[mcp_servers.mne]
opencode	~/.config/opencode/opencode.json	mcp.mne

Manual setup

Point command at the Python where you installed the package (or mne-mcp if it is on PATH).

Claude Code — ~/.claude.json:

{ "mcpServers": { "mne": { "type": "stdio", "command": "mne-mcp", "args": ["serve", "--transport", "stdio"] } } }

Codex CLI — ~/.codex/config.toml:

[mcp_servers.mne]
command = "mne-mcp"
args = ["serve", "--transport", "stdio"]
enabled = true

opencode — ~/.config/opencode/opencode.json:

{ "mcp": { "mne": { "type": "local", "command": ["mne-mcp", "serve", "--transport", "stdio"], "enabled": true } } }

Environment variables (optional .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

Configure analysis defaults (interactive wizard)

Set the defaults the structured tools fall back to — mains line frequency (50/60 Hz), default montage, filter band, EEG rejection threshold, ICA method/components, epoch window, directories, and timeout:

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

Defaults are saved to ~/.mne-mcp/config.json (override path with MNE_MCP_CONFIG). Precedence at runtime: environment variable > config file > built-in. View the active config in-session with the mne_get_config tool. Restart the MCP server for changes to take effect.

Install the Skills

mne-mcp setup installs all bundled skills automatically. To do it by hand, copy every folder under skills/ into your skills dir — the suite is mne-analyst, mne-mcp-guard, mne-methodology-critic, plus the per-category analysis skills (mne-preprocess, mne-artifacts, mne-erp, mne-spectral, mne-timefreq, mne-connectivity, mne-source, mne-decoding, mne-stats, mne-advanced) and the write-up skill (mne-writeup):

set SKILLS_DIR=%USERPROFILE%\.claude\skills
for %S in (mne-analyst mne-mcp-guard mne-methodology-critic mne-preprocess mne-artifacts mne-erp mne-spectral mne-timefreq mne-connectivity mne-source mne-decoding mne-stats mne-advanced mne-writeup) do xcopy /E /I skills\%S "%SKILLS_DIR%\%S"

mne-mcp setup also installs the mne-methodology-critic subagent to ~/.claude/agents/ (the skills' Phase 3 dispatches it in an isolated context). Copy agents\mne-methodology-critic.md there by hand if installing manually.

Restart your client after installation. (Skills are a Claude Code feature; Codex / opencode use the MCP server directly.)

---

Usage

Just describe what you want:

加载 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

The assistant will:

1. Check capabilities (mne_check_status)
2. Load your recording into the persistent session
3. Run the pipeline step by step, showing figures as PNGs
4. Interpret each result in plain language
5. Archive figures + the equivalent MNE code to mne_result/

---

Output

Every plotting tool saves a PNG to the results dir and returns its path:

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

With the mne-analyst skill installed, results and the exact MNE code that produced them are archived to mne_result/ in your working directory (sequence-numbered), so the analysis is fully reproducible.

---

Available Tools (38)

Status & Session (7)

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

Data IO (2)

mne_list_files · mne_load_raw

Preprocessing (7)

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

Visualization (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

Events / Epochs / 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

Time-frequency (1)

mne_tfr_morlet

Advanced analysis (6)

mne_decode (MVPA) · mne_connectivity · mne_compute_noise_cov · mne_make_forward · mne_apply_inverse · mne_plot_source_estimate

Export (1)

mne_save

Anything still not covered — BIDS, custom statistics, beamformers, autoreject — is reachable through mne_run_code in the same live session. See TOOLS_REFERENCE.md for full parameter details. Advanced tools need the [full] extra (pip install -e ".[full]").

---

Development

# Compile check
python -m compileall src/mne_mcp

# Run tests
pytest

# CLI commands
mne-mcp status            # Check environment
mne-mcp setup             # Register in Claude Code / Codex / opencode + install skills
mne-mcp configure-claude  # Claude Code only

---

License

MIT — see LICENSE

Documentation

• 项目介绍 / Introduction: docs/INTRODUCTION.md · .docx
• 安装说明 / Install guide: docs/INSTALL.md · .docx
• 使用介绍 / Usage guide: docs/USAGE.md · .docx
• Quick start: QUICK_START.md
• Tool reference: TOOLS_REFERENCE.md

Links

• MNE-Python: https://mne.tools/
• MCP Protocol: https://modelcontextprotocol.io