EEGLAB-MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
EEGLAB-MCP
An MCP (Model Context Protocol) server that lets an AI agent drive a real MATLAB/EEGLAB installation for reproducible EEG analysis: inspection, preprocessing, ICA, epoching, ERP, spectral analysis and quality control. Every result comes from an actual MATLAB run — there is no simulation layer — and every call returns structured data, artifacts, parameter records and logs that can be checked afterwards.
中文简介:本服务把 MCP 智能体接到真实的 MATLAB/EEGLAB 上,提供 20 个受控工具, 覆盖数据检查、预处理、ICA、分段、ERP、频谱、质控、批量处理与方法学门控。 所有计算由 MATLAB 执行,结果可复核。设计文档见
docs/。
Why this exists
An LLM can plan an EEG analysis, but it cannot be trusted to run arbitrary MATLAB code on research data. EEGLAB-MCP separates the two:
The agent understands the request and chooses tools.
EEGLAB/MATLAB performs the computation.
This server validates parameters, enforces a path whitelist, runs methodology gates before computation, and records provenance.
The design is deliberately conservative: no tool accepts MATLAB code, no tool writes to the original data, and no result is ever invented.
Related MCP server: matlab-mcp-server-python
Repository layout
Path | Contents |
| CI workflow and issue / pull-request templates |
| Example configuration (MATLAB and EEGLAB paths, input whitelist, limits) |
| Methodology, interoperability and a complete file inventory |
| MATLAB entry point, persistent worker and native tests |
| Benchmark, job-isolation and verification scripts |
| MCP server, tools, gates, security and the knowledge base |
| MATLAB-free unit tests and MATLAB integration tests |
A file-by-file inventory is in docs/STRUCTURE.md.
Requirements
Component | Requirement | Notes |
Python | 3.12 |
|
MATLAB | R2023a (verified) | Newer releases are expected to work; older ones are untested |
EEGLAB | 13.0.0b (verified) | Newer releases are not tested |
OS | Windows, macOS, Linux | MATLAB must be on |
The server starts a persistent MATLAB worker to avoid paying the 10–15 s startup cost on
every call. If the worker dies or stops responding, it falls back to a one-shot
matlab -batch process instead of hanging.
Quick start
git clone https://github.com/weichuguang/eeglab-mcp.git
cd eeglab-mcp
python -m venv .venv
# Windows
.venv\Scripts\python -m pip install -e .
# macOS / Linux
.venv/bin/python -m pip install -e .
cp config/default.example.yaml config/default.yamlEdit config/default.yaml and set at least:
matlab:
executable: "matlab" # or an absolute path
driver_dir: "../matlab"
eeglab:
root: "/path/to/eeglab"
paths:
allowed_input_roots:
- "/path/to/eeg_data"Relative paths are resolved against the config/ directory. Then verify:
python -m eeglab_mcp.server # starts the stdio server; Ctrl+C to stop
python -m pytest tests -q -m "not integration"For a full capability check (requires MATLAB and EEGLAB):
python scripts/verify_e2e.py # writes outputs/VERIFICATION_REPORT.md
python scripts/verify_stdio.py # real MCP client over stdioClient configuration
The server is a standard stdio MCP server. Use the absolute path to the virtual
environment's Python so the client does not depend on PATH.
Claude Code / Claude Desktop (.mcp.json or claude_desktop_config.json):
{
"mcpServers": {
"eeglab": {
"command": "/absolute/path/to/eeglab-mcp/.venv/bin/python",
"args": ["-m", "eeglab_mcp.server"],
"env": {
"EEGLAB_MCP_CONFIG": "/absolute/path/to/eeglab-mcp/config/default.yaml"
}
}
}
}On Windows use ...\\.venv\\Scripts\\python.exe.
VS Code (.vscode/mcp.json):
{
"servers": {
"eeglab": {
"type": "stdio",
"command": "/absolute/path/to/eeglab-mcp/.venv/bin/python",
"args": ["-m", "eeglab_mcp.server"],
"env": {
"EEGLAB_MCP_CONFIG": "/absolute/path/to/eeglab-mcp/config/default.yaml"
}
}
}
}Restart the client and ask: “List the EEGLAB tools you can use.” A healthy server returns
tool names such as eeglab_get_status and eeglab_inspect_dataset.
Tools (20)
Data access and inspection
Tool | Purpose |
| MATLAB version, EEGLAB path, availability of core functions. Call this first. |
| List |
| Sampling rate, channels, duration, events, |
| Validate and stage a copy in a job directory; the original is never modified. |
| EDF / BDF / CNT / BrainVision → |
| Logs, parameters and artifact checksums of a previous job. |
Preprocessing and core analysis
Tool | Purpose |
| Zero-phase FIR high/low/band-pass and notch; cutoff checked against Nyquist. |
| Average or explicit channel reference. |
| Epoch around event codes; window validated. |
| Baseline correction over a specified window. |
|
|
| Condition average; exports the full channel × time matrix as CSV. |
| ERP waveform, scalp topography or PSD as PNG. |
| Amplitude statistics, flat/outlier channels, event quality, and the checks not performed. |
Batch and interoperability
Tool | Purpose |
| Process many |
|
|
| Long table ( |
Methodology layer
Tool | Purpose |
| List the 39 method profiles with parameters, citations, gates and executability. |
| Query the 47 curated claims with source locators and risk notes. |
| Dry run: which gates would fire for a file and a parameter set, without computing. |
Preprocessing tools run their methodology gates before any computation. A blocked call
returns GATE_BLOCKED and produces no output. Overriding a block requires a written reason
(≥ 20 characters) that is stored with the original finding.
Return envelope
{
"success": true,
"job_id": "3f2a...",
"action": "inspect",
"result": {"...": "structured result"},
"warnings": ["Channel locations are not defined ..."],
"errors": [],
"artifacts": [{"path": "...", "kind": "eeglab_set", "bytes": 153880, "sha256": "..."}],
"provenance": {"matlab_version": "...", "eeglab_root": "...", "job_id": "..."},
"runtime": {"wall_seconds": 14.5, "job_dir": "..."},
"interpretation_limits": ["success=true means the computation completed; ..."]
}
success: truemeans the program ran. It does not mean the scientific conclusion is valid. An ERP being computed is not evidence of a significant condition difference; a successful ICA decomposition is not evidence that artifacts were removed correctly.
Safety model
Path whitelist. Inputs must be absolute paths that resolve (after
realpath) insideallowed_input_rootsoroutput_root. Traversal and symlink escapes are rejected.No arbitrary code execution. No tool accepts a MATLAB code string; there is no
evalor script concatenation. Every action is dispatched frommatlab/run_job.m.Double validation. Parameters are checked in Python and again in MATLAB.
Read-only source data. Writes go to per-job directories;
load_datasetreturns the source SHA-256.Timeouts and logs. Each job keeps
job.json,matlab_result.jsonandmatlab_stdout.log.Methodology gates. 47 claims and 39 method profiles are checked before computation.
Facts from the file. Gates read real header properties from the
.setfile, not caller claims.
Testing
# Fast unit tests: no MATLAB needed (<1 s)
python -m pytest tests -q -m "not integration"
# Integration tests: start a real MATLAB process
python -m pytest tests -q
# Native MATLAB tests (29 checks): real EEGLAB functions and a known-answer ERP
python scripts/run_matlab_tests.py
# End-to-end verification and protocol-level check
python scripts/verify_e2e.py
python scripts/verify_stdio.pyCI runs the MATLAB-free unit tests on Ubuntu and Windows with Python 3.12. Integration and end-to-end tests require a licensed MATLAB installation and are run locally.
Performance (reference machine)
Measured with scripts/benchmark_timings.py; medians, not best-case values.
Operation | Cold start (new process each call) | Persistent worker |
| 12.2 s | 0.20 s |
| 13.9 s | 0.81 s |
| 14.9 s | 1.07 s |
| 25.6 s | 1.43 s |
Seven-step chain | 110.9 s | 5.6 s |
Reference machine: Intel Xeon E-2388G, 64 GB RAM, Windows 11 22H2, MATLAB R2023a, EEGLAB 13.0.0b, Python 3.12.10, EEGLAB sample dataset (32 channels, 128 Hz, 30 504 points, 154 events). The worker start-up itself takes about 5.6 s on the first call.
Known limitations
BIOSIG dependency.
.edf/.bdfimport goes throughpop_biosig; a broken plugin fails loudly rather than silently degrading.Sequential batch.
batch_processruns files one after another in one MATLAB session; the cap islimits.max_batch_files.No channel locations, no topomap. The EEGLAB sample dataset has no
chanlocs; the topomap tool reports this explicitly instead of drawing a misleading map.ICA components are never rejected automatically. Rejection requires explicit criteria and human confirmation.
pop_runicaworkaround. EEGLAB 13'spop_runicacreates a GUI figure that fails on modern MATLAB. The server callsrunicadirectly inmatlab/ica_decompose.mand writes the decomposition back. This is documented in the results; equivalence withpop_runicahas not been verified element by element.Objects do not persist across calls. The MATLAB process persists; workspace objects do not. Intermediate results are chained through artifact files.
No
run_codeescape hatch. Capability is bounded by the 20 tools, by design.Unit inference. V vs µV is inferred from amplitude and reported as
input_unit_assumed; unusual data can be misclassified.
Documentation
Document | Contents |
Knowledge base, gate engine and override policy | |
Hand-off contract with MNE-MCP / Pingouin-MCP |
Contributing
Issues and pull requests are welcome. Please read CONTRIBUTING.md and
run the unit tests before submitting. Security reports should follow SECURITY.md.
License
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Build, validate, and deploy multi-agent AI solutions from any AI environment.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Real desktops for AI agents, on machines you choose: screenshot, type, click, hire more agents.
AI-native programming language and toolchain for accountable, verifiable agent-driven development.
Related MCP Servers
- AlicenseBqualityDmaintenanceIntegrates MATLAB with AI to execute code, generate scripts from natural language, and access MATLAB documentation seamlessly.254Apache 2.0
- AlicenseAqualityCmaintenanceMCP server that connects any AI agent to MATLAB — execute code, async jobs, interactive Plotly plots, custom tools, and monitoring dashboard2024 PyPI4MIT
- AlicenseBqualityDmaintenanceA powerful MCP server that integrates MATLAB with AI, allowing you to execute MATLAB code, generate MATLAB scripts from natural language descriptions, and access MATLAB documentation directly through your AI assistant.2Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables remote execution of MATLAB experiments via natural language, with tools for code execution, task management, file transfer, and system diagnostics.-