ephys-mcp

An MCP server that lets an LLM analyse intracortical (spike-level) brain-computer-interface recordings: signal quality, spike detection, firing rates, and cursor-velocity decoding.

Existing BCI MCP servers target scalp EEG. This one targets the kind of data a high-channel-count implant produces, and defines a read-only adapter contract so a live device backend can be added when a vendor publishes an API.

Research and education software. Not a medical device. Not for clinical use. Not affiliated with or endorsed by Neuralink Corp. or any other implant manufacturer.

Status

v0.1, early. Working today: local NWB files, local broadband WAV recordings, streaming from the DANDI Archive, a synthetic motor-cortex source with ground truth, spike detection, quality metrics, ridge and Kalman decoders, trial-aligned PSTHs, and figures. Planned: PyPI release and registry listings.

Related MCP server: hypernmnesia-mcp-viz

Install and run

uv sync
uv run ephys-mcp        # stdio transport

Claude Code:

claude mcp add ephys -- uv --directory /path/to/ephys-mcp run ephys-mcp

Claude Desktop (claude_desktop_config.json):

{ "mcpServers": { "ephys": { "command": "uv", "args": ["--directory", "/path/to/ephys-mcp", "run", "ephys-mcp"] } } }

Then ask, for real data: "Find a small motor cortex dataset on DANDI, open it, and tell me how well hand velocity can be decoded." Or offline: "Open a synthetic session, check signal quality, fit a Kalman decoder and show me a decoded window."

Data sources

Dataset licence and citation come from the archive and are returned by open_session, so the model can attribute the data. Many datasets record only during trials; the server tracks those spans (recorded_fraction) and leaves the gaps out of rates and decoding instead of reading them as silence.

WAV samples carry no physical unit, so amplitudes are reported as ADC counts unless you pass uv_per_count; every amplitude result names its unit. Clips in a folder are separate recordings, so the server says that timing across those channels is not meaningful. Spike times from WAV are threshold crossings, not sorted units.

Reference result on MC_Maze_Small (DANDI 000140, 142 units, last 20% held out, 50 ms bins): ridge R² 0.50, Kalman R² 0.34 for hand velocity. These are simple causal linear baselines, not state of the art.

Tools

Resource: ephys://sessions. Prompt: analyze_session.

Tools return summaries, never raw arrays, so results fit in a model's context.

Plot tools return the PNG inline, so a vision-capable model can read the figure, and also save it under ~/.cache/ephys-mcp/plots (override with EPHYS_MCP_OUTPUT_DIR). Figures use a categorical palette checked for colour-blind separation, with direct labels so identity never rests on colour alone.

Design rules

• Read-only. The NeuralSource contract has no write, stimulate or configure method. None will be added without a separate safety design.

• Local by default. stdio transport, no telemetry. Neural data is sensitive.

• No bundled third-party data. See DATA_LICENSES.md.

Writing a source adapter

Subclass ephys_mcp.sources.base.NeuralSource (info, read_raw, spike_times, behavior) and register it in ephys_mcp/sources/__init__.py. sources/n1_stub.py documents what a live implant adapter would need.

Development

uv run pytest              # offline
uv run pytest -m network   # also streams a real file from DANDI
uv run ruff check .

Licence

CC0 1.0 Universal. The authors waive all copyright and related rights to the extent the law allows. Use it for anything, no attribution required. CC0 does not grant patent or trademark rights.