{
"markdown": "\n\n\n\n# โก๐ง eeg-mcp\n\n### Real-time EEG for AI agents โ stream, replay, visualize, record, stimulate\n\n[](https://pypi.org/project/eeg-mcp/)\n[](https://pypi.org/project/eeg-mcp/)\n[](https://aimplifier.github.io/eeg-mcp/)\n[](LICENSE)\n\n**[Documentation](https://aimplifier.github.io/eeg-mcp/)** ยท\n**[Tutorial](https://aimplifier.github.io/eeg-mcp/examples/tutorial-first-realtime-session/)** ยท\n**[Hardware](https://aimplifier.github.io/eeg-mcp/hardware/)** ยท\n**[Safety](https://aimplifier.github.io/eeg-mcp/safety/)** ยท\n**[Tool Reference](https://aimplifier.github.io/eeg-mcp/tools/)**\n\n
\n\nA Model Context Protocol server that gives an AI agent one interface over the\n**live** EEG workflow: acquisition from ~66 [BrainFlow](https://brainflow.readthedocs.io)\nboards, wall-clock replay of existing recordings, stateful online DSP, a live\nbrowser monitor, crash-safe recording, and gated stimulation output.\n\nThe offline counterpart is **[neuro-mcp](https://github.com/AImplifier/neuro-mcp)**\n(MNE processing, source imaging, BIDS/EHR storage). This is the real-time half โ\neverything that has to happen while the signal is still arriving.\n\n## Concept\n\n```mermaid\nflowchart LR\n Researcher([\"๐ฌ BCI Researcher\"])\n Clinician([\"๐ฉบ Clinician\"])\n Agent[[\"๐ค AI Agent\"]]\n Server((\"eeg-mcp
FastMCP ยท 47 tools\"))\n\n Clinician -- talks to --> Agent\n Researcher -- talks to --> Agent\n Agent -- MCP --> Server\n\n Server --> Acquire[\"Acquire
66 boards ยท replay
at true rate\"]\n Server --> Process[\"Process
stateful online DSP
custom plugins\"]\n Server --> Watch[\"Watch & Record
live monitor ยท HTML
crash-safe .fif\"]\n Server --> Stim[\"Stimulate
LSL ยท TTL ยท TMS/tES
3 safety gates\"]\n\n classDef acq fill:#14b8a6,stroke:#0d9488,color:#fff\n classDef proc fill:#4f8cff,stroke:#2f5fbf,color:#fff\n classDef viz fill:#b06fe0,stroke:#7c3fae,color:#fff\n classDef stim fill:#eb5757,stroke:#b93b3b,color:#fff\n class Acquire acq\n class Process proc\n class Watch viz\n class Stim stim\n```\n\nNobody calls a tool by hand โ you talk to an agent in plain English and it\ndrives the 47 tools underneath. The\n**[tutorial](https://aimplifier.github.io/eeg-mcp/examples/tutorial-first-realtime-session/)**\nshows what that looks like end to end, with no hardware required.\n\n## What it does\n\n\n\n| \n\n**๐ก Stream**\n\n66 BrainFlow board identifiers โ OpenBCI, Muse, ANT Neuro, g.tec, Mentalab and\nmore โ plus a synthetic board that needs no hardware. Samples land in a ring\nbuffer filled by a background thread, so tool calls read a live view instead of\nblocking on a device.\n\n | \n\n\n**โช Replay**\n\nPlay an EDF/BDF/GDF/SET/FIF or BrainFlow CSV *at the rate it was recorded*,\nre-emitting annotations as events at their original timings. Adds speed, seek,\npause and looping. A pipeline developed against a file runs **unchanged**\nagainst hardware.\n\n | \n
\n\n| \n\n**๐ Visualize**\n\nA loopback-bound, token-gated live browser view: rolling traces, event markers,\nband power, per-electrode quality, and transport controls. Plus self-contained\nHTML reports โ no CDN, no external assets, opens on an air-gapped machine.\n\n | \n\n\n**๐พ Record**\n\nWrite continuously to MNE-native `.fif` with the event log attached as\nannotations, plus a metadata row in a store **schema-compatible with\nneuro-mcp**. Crash-safe: an interrupted session is recoverable.\n\n | \n
\n\n| \n\n**๐งฉ Extend**\n\nPlug in your own real-time processor โ feature extractor, classifier, artifact\ngate, or **EEG tokenizer for sequence models** โ and it runs on the same footing\nas the built-ins, inside the acquisition loop.\nโ [Extending](https://aimplifier.github.io/eeg-mcp/extending/)\n\n | \n\n\n**โก Stimulate**\n\nOne `send_stim_event` contract over pluggable backends: LSL for software,\nBrainFlow's marker channel for sample-aligned embedding, serial/TTL and\ntemplated ASCII for hardware including TMS and tES โ behind three safety gates.\n\n | \n
\n
\n\n> [!NOTE]\n> **One event log.** Board markers, replayed annotations, dispatched\n> stimulations and manual notes all land in the same table on the same clock, with\n> absolute sample indices. A closed-loop run reconstructs afterwards with no clock join.\n\n## Install\n\n```bash\nconda create -n eeg-mcp python=3.11 -y && conda activate eeg-mcp\npip install eeg-mcp\n```\n\n\nOptional extras and MCP client registration
\n\n
\n\n```bash\npip install \"eeg-mcp[lsl]\" # LSL marker outlets (PsychoPy, OpenViBE, ...)\npip install \"eeg-mcp[serial]\" # serial/TTL trigger delivery to hardware\n```\n\nRegister with an MCP client using an **absolute path** to the env's interpreter:\n\n```json\n{\n \"mcpServers\": {\n \"eeg-realtime\": {\n \"command\": \"/path/to/envs/eeg-mcp/bin/python\",\n \"args\": [\"-m\", \"eeg_mcp\"]\n }\n }\n}\n```\n\nOr with the Claude Code CLI:\n\n```bash\nclaude mcp add eeg-realtime -- /path/to/envs/eeg-mcp/bin/python -m eeg_mcp\n```\n\nโ Full guide: **[Installation](https://aimplifier.github.io/eeg-mcp/installation/)**\n\n \n\n## Quick start\n\nAsk your agent for the outcome; it picks the calls. No hardware required:\n\n```python\nstart_stream(session_id=\"s1\", board=\"synthetic\")\ncheck_signal_quality(session_id=\"s1\") # before trusting anything\nset_filters(session_id=\"s1\", bandpass_low=1, bandpass_high=40, notch_freq=50)\nget_band_power(session_id=\"s1\", seconds=2)\nstart_monitor(session_id=\"s1\") # โ open the returned URL\n```\n\nReplay a real recording as if it were live, then keep the record:\n\n```python\ninspect_recording(path=\"sub-04_rest.edf\")\nstart_replay(session_id=\"r1\", path=\"sub-04_rest.edf\", speed=1.0)\nget_events(session_id=\"r1\", origin=\"annotation\")\nexport_report(session_id=\"r1\", notes=\"Routine review.\")\n```\n\n\n\n```mermaid\nflowchart LR\n A[\"start_stream
or start_replay\"] --> B[check_signal_quality]\n B --> C[set_filters]\n C --> D[\"get_band_power
get_psd\"]\n C --> E[start_monitor]\n C --> P[attach_processor]\n A --> R[start_recording]\n D --> S[send_stim_event]\n P --> S\n R --> X[stop_recording]\n S --> X\n E --> X\n X --> Z[stop_stream]\n\n classDef hot fill:#14b8a6,stroke:#0d9488,color:#fff\n class A,X hot\n```\n\n
\n\n## Documentation\n\n| Guide | |\n|---|---|\n| ๐ **[Installation](https://aimplifier.github.io/eeg-mcp/installation/)** | Environment, client registration, troubleshooting |\n| ๐ **[Tutorial](https://aimplifier.github.io/eeg-mcp/examples/tutorial-first-realtime-session/)** | End to end, no hardware needed |\n| โช [Replay-Driven Development](https://aimplifier.github.io/eeg-mcp/examples/replay-driven-development/) | Build against a recording, deploy live |\n| ๐ [Closed-Loop Neurofeedback](https://aimplifier.github.io/eeg-mcp/examples/closed-loop-neurofeedback/) | Feature โ trigger, with a measured latency budget |\n| ๐ฉบ [Live Clinical Review](https://aimplifier.github.io/eeg-mcp/examples/clinical-live-review/) | Visual review, annotation, reporting |\n| โก [Stimulation Protocols](https://aimplifier.github.io/eeg-mcp/examples/stimulation-protocols/) | TMS and tES through the safety gates |\n| ๐งฉ [Extending](https://aimplifier.github.io/eeg-mcp/extending/) | Write a custom processor or EEG tokenizer |\n| ๐ [Supported Hardware](https://aimplifier.github.io/eeg-mcp/hardware/) | All 66 boards, formats, stimulation transports |\n| โ ๏ธ [Safety](https://aimplifier.github.io/eeg-mcp/safety/) | **Read before connecting a stimulator** |\n| ๐ [Tool Reference](https://aimplifier.github.io/eeg-mcp/tools/) | All 47 tools |\n\n## The one design decision worth knowing\n\n> [!IMPORTANT]\n> **Filtering happens in the producer thread, not at query time.**\n\nA stateful IIR filter must see every sample exactly once, in order. The common\nshortcut โ filtering each query window independently โ restarts the filter at\nevery window boundary and injects a transient each time. It is invisible in a\nband-power plot and **fatal for anything phase-sensitive**.\n\nSo the producer filters each chunk once as it arrives, carrying `sosfilt`\ndelay-line state forward, and writes to a second ring buffer. Queries just read.\n\n```mermaid\nflowchart LR\n BF[Board / Recording] -->|poll| PR{{Producer thread}}\n PR -->|raw chunk| RB[(Raw ring buffer)]\n PR -->|stateful sosfilt| FB[(Filtered ring buffer)]\n PR -->|markers & annotations| EL[(Event log)]\n PR -->|append| DISK[(.fif on disk)]\n PR -->|streaming| PL[Your processors]\n RB & FB & EL --> Q[MCP tools]\n\n classDef hot fill:#14b8a6,stroke:#0d9488,color:#fff\n class PR hot\n```\n\nThe test suite asserts chunked filtering matches whole-signal filtering to\n**1e-9**, *and* asserts as a control that the naive approach does not.\n\n| Consequence | |\n|---|---|\n| Filters are **causal** | No zero-phase option โ that needs future samples. `stream_status` reports `group_delay_sec` |\n| Both buffers are kept | `read_window(filtered=false)` always gets raw signal, to check whether a feature is real or an artifact |\n| Indices are shared | An event's `sample_index` means the same thing in either buffer |\n\n> [!TIP]\n> Budget a closed loop as **group delay + poll interval + dispatch latency** โ\n> measured at **~71 ms** in the reference configuration. Good for neurofeedback;\n> not adequate for phase-locked stimulation.\n\n## Stimulation safety\n\n> [!CAUTION]\n> **This software is not a medical device and has not been validated for\n> clinical use.** TMS and tES can cause harm, **including seizure**. Use only\n> under a protocol approved by your ethics board, on a rig whose device-level\n> interlocks are intact, with a trained operator present.\n\nThree gates apply to every hardware backend:\n\n| # | Gate | Effect |\n|---|---|---|\n| 1 | **Config** | Hardware backends refuse to open unless the server was started with `EEG_MCP_ALLOW_HARDWARE_STIM=1`. **An agent cannot set this.** |\n| 2 | **Arming** | `arm_stim` permits dispatch for a window that *expires*, so a stalled agent cannot resume and fire later |\n| 3 | **Limits** | Intensity, duration and interval are clamped; violations **raise** rather than silently saturate |\n\nNone of this replaces the interlocks on the device itself.\n\n> [!WARNING]\n> **The hardware backends are generic transports driven by command templates you\n> supply from your device's manual โ not vendor drivers, and none has been tested\n> against a physical stimulator.** A plausible-looking untested driver would be\n> worse than none: it would fail silently while connected to something pointed at\n> a person's head.\n>\n> Start every protocol on `backend=\"log\"`, which accepts everything and emits nothing.\n\n## Verify\n\n```bash\npython testing/verify.py # core correctness\npython testing/verify_recording.py # recording + metadata store\npython testing/verify_processing.py # plugin processors\npython testing/persona_bci_researcher.py # engineer workflow\npython testing/persona_clinician.py # clinician workflow\n```\n\nAll five drive the real server through FastMCP's in-memory client and assert\nagainst **planted ground truth**:\n\n- a spike planted at an annotation onset lands at **t = 0 ยฑ 0 ms** in the\n extracted epoch โ proving annotation timing, replay clock, ring-buffer\n indexing and epoch extraction all agree;\n- a deliberately **broken plugin cannot stop acquisition** โ throughput holds at 1.0;\n- hardware stimulation is **refused** while the config gate is unset.\n\nโ **[What is and is not covered](https://aimplifier.github.io/eeg-mcp/testing/)** โ\nincluding an honest list of what has never been tested against real hardware.\n\n## License\n\nBSD-3-Clause. See **[LICENSE](LICENSE)** and **[NOTICE](NOTICE)**.\n\n\n
\n\n**[โฌ back to top](#-eeg-mcp)** ยท Part of the\n**[AImplifier](https://github.com/AImplifier)** neuro toolchain ยท\nsibling project **[neuro-mcp](https://github.com/AImplifier/neuro-mcp)**\n\n
\n",
"bytes": 12459,
"sha": "85094ee2297dd44ff8d10d85f11b1dcffc79a5656212264c4cdf9e4a8d14c44d",
"repo_slug": "aimplifier/eeg-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_aimplifier_eeg_mcp_d11cebb1/readme"
}