{
  "markdown": "<!-- mcp-name: io.github.Exekiel179/mne-mcp -->\n\n# MNE-MCP\n\n[![CI](https://github.com/Exekiel179/MNE-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/Exekiel179/MNE-MCP/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![MCP](https://img.shields.io/badge/protocol-MCP-green.svg)](https://modelcontextprotocol.io)\n\n**English** | [简体中文](README.zh-CN.md)\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that gives AI assistants\ndirect, conversational access to **[MNE-Python](https://mne.tools/)** for analyzing human\nneurophysiology data — **EEG, MEG, sEEG, ECoG, and fNIRS**.\n\nDescribe your analysis in plain language — MNE-MCP loads your recording, runs the MNE pipeline\n(filtering, ICA, epoching, ERP/ERF averaging, time-frequency, source-level work via code),\nsaves the figures, and explains the results.\n\n> Works in **Claude Code** and **opencode** (any MCP-capable client). Pairs with bundled\n> Agent **Skills** — `mne-analyst`, `mne-mcp-guard`, plus a skeptical **analysis suite**\n> (`mne-methodology-critic` + per-category skills) for reliable, archived workflows.\n\n---\n\n## Why an MCP for MNE-Python?\n\nMNE analysis is **stateful and visual** — unlike a one-shot statistics batch job:\n\n- You load a `Raw` recording once, then filter → re-reference → fit ICA → epoch → average →\n  time-frequency, each step mutating large in-memory objects. MNE-MCP keeps **one persistent\n  session** so recordings never get re-loaded between steps.\n- Every decision is driven by **looking** (PSD, sensor maps, ICA components, ERPs). Every plotting\n  tool saves a **PNG** the assistant can read and interpret.\n- MNE is a huge pure-Python API. MNE-MCP gives you **38 structured tools** spanning the common\n  pipeline *and* advanced analysis (source localization, connectivity, decoding), plus an\n  **`mne_run_code`** escape hatch that reaches the entire MNE API in the same live session.\n- Defaults (line frequency, montage, filter band, rejection threshold, ICA settings, epoch window,\n  dirs, timeout) are **user-configurable** via an interactive `mne-mcp configure` wizard.\n\n---\n\n## Requirements\n\n- Python 3.10+\n- [MNE-Python](https://mne.tools/) ≥ 1.6 — **provisioned on demand** (see [Lightweight by default](#lightweight-by-default--on-demand-backend)); install it up front with `mne-mcp[analysis]` if you prefer\n- `scikit-learn` for ICA (in the `ica` / `full` extras, or `mne-mcp install-backend`)\n- Claude Code (or any MCP client) with MCP support\n\n> Cross-platform: unlike a closed engine, MNE-Python is pure Python, so analysis tools work on\n> Windows, macOS, and Linux.\n\n---\n\n## Quick Install\n\n```bash\ngit clone https://github.com/Exekiel179/MNE-MCP.git\ncd MNE-MCP\n\n# 1. Install (pulls in mne, numpy, scipy, matplotlib, scikit-learn for ICA)\npip install -e \".[ica]\"\n\n# 2. Register in your MCP client(s) — Claude Code, Codex, opencode — and install skills\nmne-mcp setup\n\n# 3. Restart your client\n```\n\nOr run the **one-shot installer** (creates the venv, installs, verifies, registers, installs skills):\n\n```powershell\npwsh -File scripts\\install.ps1     # Windows\n```\n```bash\nbash scripts/install.sh            # macOS / Linux\n```\n\nSee [QUICK_START.md](QUICK_START.md) for a guided first session, or [docs/INSTALL.md](docs/INSTALL.md)\nfor the full guide.\n\n> **One command does everything:** `mne-mcp setup` registers the `mne` server in **Claude Code,\n> Codex, and opencode** (whichever you use) *and* installs the companion skills. Narrow it with\n> `--clients claude,codex`. The `mne_*` tools require **one client restart** afterwards (MCP servers\n> load at startup).\n\n### Run via `uvx` / `pipx` (standard MCP — recommended)\n\n`mne-mcp` is [published on PyPI](https://pypi.org/project/mne-mcp/), so the most portable path is the\nstandard MCP launcher — no clone, no `setup`. Add this to your client config (`~/.claude.json` for\nClaude Code, `claude_desktop_config.json` for Claude Desktop):\n\n```json\n{ \"mcpServers\": { \"mne\": { \"command\": \"uvx\", \"args\": [\"--from\", \"mne-mcp[ica]\", \"mne-mcp\", \"serve\", \"--transport\", \"stdio\"] } } }\n```\n\n`uvx` (from [uv](https://docs.astral.sh/uv/)) fetches and runs `mne-mcp` on demand. The `[ica]` extra\npulls in scikit-learn so ICA works out of the box; swap it for **`mne-mcp[full]`** to also get the\nadvanced tools (source localization, connectivity, decoding, BIDS). Because MNE pulls in a large\nscientific stack, a **persistent** install is usually snappier than re-resolving each run:\n\n```bash\npipx install \"mne-mcp[ica]\"        # or: uv tool install \"mne-mcp[ica]\"  (use [full] for advanced tools)\n```\n\nthen set the config `command` to `mne-mcp` with `args: [\"serve\", \"--transport\", \"stdio\"]`. The source\ninstall above remains the path for development.\n\n**No `uv`? Bootstrap `pipx` with plain Python, then install and register in one go:**\n\n```bash\npython -m pip install --user pipx\npython -m pipx ensurepath          # reopen your terminal so `pipx` lands on PATH\npipx install mne-mcp               # lightweight; provision the backend on demand\nmne-mcp setup                      # register in clients + install skills\nmne-mcp install-backend            # add MNE + ICA (or let the mne_install_backend tool do it)\n```\n\n> **Skills are bundled in the package (since 0.2.2).** A PyPI install carries the skill suite and the\n> `mne-methodology-critic` agent, so one extra command installs them — `mne-mcp setup` (after `pipx`/\n> `uv tool install`) or `uvx mne-mcp setup`. No clone required.\n\n### Lightweight by default — on-demand backend\n\nSince **0.3.0** the package itself is tiny: a bare `pip install mne-mcp` / `pipx install mne-mcp`\npulls in only the MCP protocol layer (`mcp`, `fastmcp`, `pydantic`, `python-dotenv`), so it installs\nin seconds. The heavy scientific stack (MNE-Python + numpy/scipy/matplotlib/pandas, and scikit-learn\nfor ICA) is **provisioned the first time an analysis needs it**:\n\n- In a session, just ask — when a tool reports the backend is missing, call the **`mne_install_backend`**\n  tool (or it is offered by `mne_check_status`). It `pip install`s into the server's own environment and\n  becomes usable **without a client restart**.\n- From a terminal: `mne-mcp install-backend` (add `--profile full` for source localization / connectivity\n  / decoding / BIDS).\n\n```bash\npipx install mne-mcp            # tiny, instant\nmne-mcp install-backend        # add MNE + ICA when you're ready (or let the tool do it)\n```\n\nPrefer everything up front? Install an extra instead: **`mne-mcp[analysis]`** (MNE core), **`[ica]`**\n(+ scikit-learn), or **`[full]`** (+ advanced tools). For ephemeral `uvx` runs, pin the extra in the\nconfig (`--from mne-mcp[ica]`, as above) since an `uvx` environment is discarded between runs, so an\non-demand install would not persist.\n\n---\n\n## Configuration\n\n### Auto-configure (recommended)\n\n```bash\nmne-mcp setup                          # Claude Code + Codex + opencode, plus skills\nmne-mcp setup --clients claude,codex   # only specific clients\nmne-mcp configure-claude               # Claude Code only (subset of setup)\n```\n\n`setup` registers the `mne` server in each client and installs the skills, writing a timestamped\nbackup of any file it touches:\n\n| Client | Config file | Key |\n|---|---|---|\n| Claude Code | `~/.claude.json` | `mcpServers.mne` |\n| OpenAI Codex CLI | `~/.codex/config.toml` | `[mcp_servers.mne]` |\n| opencode | `~/.config/opencode/opencode.json` | `mcp.mne` |\n\n### Manual setup\n\nPoint `command` at the Python where you installed the package (or `mne-mcp` if it is on PATH).\n\n**Claude Code** — `~/.claude.json`:\n```json\n{ \"mcpServers\": { \"mne\": { \"type\": \"stdio\", \"command\": \"mne-mcp\", \"args\": [\"serve\", \"--transport\", \"stdio\"] } } }\n```\n\n**Codex CLI** — `~/.codex/config.toml`:\n```toml\n[mcp_servers.mne]\ncommand = \"mne-mcp\"\nargs = [\"serve\", \"--transport\", \"stdio\"]\nenabled = true\n```\n\n**opencode** — `~/.config/opencode/opencode.json`:\n```json\n{ \"mcp\": { \"mne\": { \"type\": \"local\", \"command\": [\"mne-mcp\", \"serve\", \"--transport\", \"stdio\"], \"enabled\": true } } }\n```\n\n### Environment variables (optional `.env`)\n\n```ini\nMNE_MCP_TIMEOUT=300          # per-operation timeout (s); raise for ICA / TFR / large files\nMNE_MCP_RESULTS_DIR=...      # where figures + exported objects are saved\nMNE_MCP_DATA_DIR=...         # default directory mne_list_files scans\n```\n\n### Configure analysis defaults (interactive wizard)\n\nSet the defaults the structured tools fall back to — mains line frequency (50/60 Hz), default\nmontage, filter band, EEG rejection threshold, ICA method/components, epoch window, directories,\nand timeout:\n\n```bash\nmne-mcp configure            # interactive prompts (Enter keeps current value)\nmne-mcp configure --show     # print current defaults\nmne-mcp configure --reset    # back to built-in defaults\nmne-mcp configure --set line_freq=60 default_montage=biosemi64 reject_eeg_uv=120   # non-interactive\n```\n\nDefaults are saved to `~/.mne-mcp/config.json` (override path with `MNE_MCP_CONFIG`). Precedence at\nruntime: **environment variable > config file > built-in**. View the active config in-session with the\n`mne_get_config` tool. Restart the MCP server for changes to take effect.\n\n### Install the Skills\n\n`mne-mcp setup` installs all bundled skills automatically. To do it by hand, copy every folder under\n`skills/` into your skills dir — the suite is `mne-analyst`, `mne-mcp-guard`, `mne-methodology-critic`,\nplus the per-category analysis skills (`mne-preprocess`, `mne-artifacts`, `mne-erp`, `mne-spectral`,\n`mne-timefreq`, `mne-connectivity`, `mne-source`, `mne-decoding`, `mne-stats`, `mne-advanced`) and the\nwrite-up skill (`mne-writeup`):\n\n```cmd\nset SKILLS_DIR=%USERPROFILE%\\.claude\\skills\nfor %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\"\n```\n\n> `mne-mcp setup` also installs the `mne-methodology-critic` **subagent** to `~/.claude/agents/` (the\n> skills' Phase 3 dispatches it in an isolated context). Copy `agents\\mne-methodology-critic.md` there\n> by hand if installing manually.\n\nRestart your client after installation. (Skills are a Claude Code feature; Codex / opencode use the\nMCP server directly.)\n\n---\n\n## Usage\n\nJust describe what you want:\n\n```\n加载 sub-01_raw.fif，看一下功率谱\n```\n```\n对 raw 做 1–40 Hz 带通、50 Hz 陷波，然后跑 ICA 去眼电\n```\n```\nEpoch around the 'target' trigger, -0.2 to 0.8 s, average it, and show the ERP topomaps at 100/200/300 ms\n```\n\nThe assistant will:\n1. Check capabilities (`mne_check_status`)\n2. Load your recording into the persistent session\n3. Run the pipeline step by step, showing figures as PNGs\n4. Interpret each result in plain language\n5. Archive figures + the equivalent MNE code to `mne_result/`\n\n---\n\n## Output\n\nEvery plotting tool saves a PNG to the results dir and returns its path:\n\n```\n> Figure: `C:\\...\\mne-mcp\\results\\psd_01.png`\n```\n\nWith the `mne-analyst` skill installed, results and the exact MNE code that produced them are\narchived to `mne_result/` in your working directory (sequence-numbered), so the analysis is\nfully reproducible.\n\n---\n\n## Available Tools (38)\n\n### Status & Session (7)\n`mne_check_status` · `mne_session_info` · `mne_describe` · `mne_get_info` ·\n`mne_reset_session` · `mne_run_code` · `mne_get_config`\n\n### Data IO (2)\n`mne_list_files` · `mne_load_raw`\n\n### Preprocessing (7)\n`mne_filter` · `mne_resample` · `mne_crop` · `mne_set_montage` ·\n`mne_set_reference` · `mne_mark_bad_channels` · `mne_interpolate_bads`\n\n### Visualization (3)\n`mne_plot_psd` · `mne_plot_raw` · `mne_plot_sensors`\n\n### ICA (4)\n`mne_fit_ica` · `mne_plot_ica_components` · `mne_plot_ica_sources` · `mne_apply_ica`\n\n### Events / Epochs / ERP (7)\n`mne_find_events` · `mne_events_from_annotations` · `mne_make_epochs` ·\n`mne_plot_epochs_image` · `mne_average_evoked` · `mne_plot_evoked` · `mne_plot_topomap`\n\n### Time-frequency (1)\n`mne_tfr_morlet`\n\n### Advanced analysis (6)\n`mne_decode` (MVPA) · `mne_connectivity` · `mne_compute_noise_cov` · `mne_make_forward` ·\n`mne_apply_inverse` · `mne_plot_source_estimate`\n\n### Export (1)\n`mne_save`\n\nAnything still not covered — BIDS, custom statistics, beamformers, autoreject — is reachable through\n**`mne_run_code`** in the same live session. See [TOOLS_REFERENCE.md](TOOLS_REFERENCE.md) for full\nparameter details. Advanced tools need the `[full]` extra (`pip install -e \".[full]\"`).\n\n---\n\n## Development\n\n```bash\n# Compile check\npython -m compileall src/mne_mcp\n\n# Run tests\npytest\n\n# CLI commands\nmne-mcp status            # Check environment\nmne-mcp setup             # Register in Claude Code / Codex / opencode + install skills\nmne-mcp configure-claude  # Claude Code only\n```\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n## Documentation\n\n- **项目介绍 / Introduction**: [docs/INTRODUCTION.md](docs/INTRODUCTION.md) · [.docx](docs/INTRODUCTION.docx)\n- **安装说明 / Install guide**: [docs/INSTALL.md](docs/INSTALL.md) · [.docx](docs/INSTALL.docx)\n- **使用介绍 / Usage guide**: [docs/USAGE.md](docs/USAGE.md) · [.docx](docs/USAGE.docx)\n- **Quick start**: [QUICK_START.md](QUICK_START.md)\n- **Tool reference**: [TOOLS_REFERENCE.md](TOOLS_REFERENCE.md)\n\n## Links\n\n- **MNE-Python**: https://mne.tools/\n- **MCP Protocol**: https://modelcontextprotocol.io\n",
  "bytes": 13453,
  "sha": "b34f88cdcce6bf0086a99cde2749492cc80a0880dc294a7ee54cf0c9e8620259",
  "repo_slug": "exekiel179/mne-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_exekiel179_mne_mcp_b54d70ca/readme"
}