BCI-MCP Server
This MCP server lets Claude/other MCP clients connect to EEG devices or a synthetic brain and work with live brain-state metrics and recordings.
Discover and connect/disconnect EEG sources, defaulting to
synthetic://.Read current brain state: focus, calm, attention, engagement, fatigue, meditation, confidence/status, band powers, and signal quality/artifacts.
Learn exact metric formulas, references, caveats, and pipeline limitations.
Calibrate a personalized baseline and annotate live streams with event markers.
Get a current brain-state snapshot via stream summary.
Record the live stream to npz/csv/edf files.
Start neurofeedback sessions for a chosen metric/target and sample the current score.
Access MCP resources (
brain://state,brain://device,brain://citations) and theinterpret_brain_stateprompt.
Provides containerized deployment of the BCI-MCP system with all necessary services, making setup easier through docker-compose
Hosts the project repository for version control and collaboration
Automates the building and deployment of documentation to GitHub Pages when changes are pushed to the main branch
Hosts the project documentation, automatically built and deployed through GitHub Actions
Provides the runtime environment for the BCI-MCP server, with special requirements for version 3.10+
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@BCI-MCP Server start recording my brain signals for 30 seconds"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
https://github.com/user-attachments/assets/8b37cebc-2b6b-40de-b440-b02ffb9b617e
BCI-MCP
Ask Claude about your brain. Focus, calm, attention. Works without a headset.
Real Model Context Protocol server for EEG. Python on the backend. Plug into Claude Desktop, Claude Code, or Cursor.
$ bci-mcp stream --device synthetic://
FOCUS ##############...... 0.71
CALM ######.............. 0.32
ATTENTION #################... 0.86
ENGAGEMENT ##############...... 0.70
alpha #### beta ####### theta ## delta # gamma ### signal: GOODContents
Related MCP server: KOI-MCP Integration
What this is
You have an EEG signal. This turns it into numbers Claude can read: focus, calm, attention, band powers, signal quality. Basically a small brain-computer interface server that stays out of your way.
No headset yet? Use the built-in fake brain (synthetic://). Same code path as real hardware. You can test the whole MCP stack before you buy anything.
Sources that work today:
Synthetic demo (no hardware)
NeuroFocus (serial or BLE)
LSL streams
Generic serial
Recorded sessions (replay from file)
Why this exists
LLMs can already read your screen and your codebase. They can't read you. This closes that gap with the one physiological signal consumer hardware does reasonably well — EEG — and hands it to Claude as plain numbers it can reason over. Concretely, people use it for:
Neurofeedback with a coach. Run
start_neurofeedbackon focus or calm and let Claude read the score, explain the trend, and adjust the session — instead of watching a bar chart alone.State-aware assistants. An agent that can tell your attention is fading can summarize instead of elaborate, or suggest a break. Focus, calm, and attention arrive as numbers any MCP client can act on.
Accessibility. A language-model front end to brain signals for motor-impaired users, where a tool call stands in for a click.
Research & prototyping. One URI scheme covers OpenBCI, Muse, LSL, serial, and file replay, so an experiment written against
synthetic://runs unchanged on real hardware. Recording and playback make sessions reproducible.
Not clinical, not diagnosis — band-power ratios for demos, neurofeedback, and research (see Docs and accuracy).
Try it in one line
Claude Code
claude mcp add bci-mcp -- npx -y bci-mcpNo Node? Use Python:
claude mcp add bci-mcp -- uvx bci-mcp serveOr let the install script pick for you:
curl -fsSL https://raw.githubusercontent.com/enkhbold470/bci-mcp/main/scripts/install-mcp.sh | bashClaude Desktop (Settings → Developer → Edit Config):
{
"mcpServers": {
"bci-mcp": {
"command": "npx",
"args": ["-y", "bci-mcp"]
}
}
}Cursor (~/.cursor/mcp.json, under mcpServers):
"bci-mcp": { "command": "npx", "args": ["-y", "bci-mcp"] }Then ask something like: Connect to the demo brain. What's my focus right now?
Published packages: pip install bci-mcp (PyPI) and npx -y bci-mcp (npm).
Deploy on Manufact Cloud
Host a public MCP endpoint on Manufact Cloud (formerly mcp-use). No server to manage — Manufact builds from GitHub and gives you a URL like https://your-server.run.mcp-use.com/mcp.
1. Deploy from GitHub
Go to manufact.com/cloud and sign in.
New server → Deploy from GitHub.
Select this repo:
enkhbold470/bci-mcp, branchmain.Manufact detects Python and the FastMCP stack automatically.
Or use the CLI (after npm i -g mcp-use and mcp-use login):
git push origin main # Manufact builds from GitHub, not your laptop
mcp-use deploy --runtime python --port 80002. Dashboard settings (important)
Use these values in the Manufact deploy form. Getting the build/start commands wrong is the most common failure mode.
Setting | Value |
Port |
|
Build command | (leave empty) |
Start command | (leave empty) — Manufact auto-starts |
If auto-detect fails, set the start command explicitly:
uvicorn bci_mcp:app --host 0.0.0.0 --port 8000Do not set a custom build command like uv sync — Manufact runs that for you.
Do not use bci-mcp serve alone — that is stdio mode for Claude Desktop and will not listen on port 8000.
3. Verify the deployment
After the build succeeds, check:
curl https://YOUR-SLUG.run.mcp-use.com/health
# → {"status":"healthy"}Your MCP endpoint:
https://YOUR-SLUG.run.mcp-use.com/mcp4. Connect an MCP client
Claude Desktop / Cursor — add a remote MCP server (streamable HTTP):
{
"mcpServers": {
"bci-mcp-cloud": {
"url": "https://YOUR-SLUG.run.mcp-use.com/mcp"
}
}
}Then ask: Connect to the demo brain — what's my focus?
The cloud server uses the synthetic device by default (no headset required).
What Manufact runs under the hood
GitHub repo
→ uv sync --frozen --no-dev (needs uv.lock in the repo — do not .dockerignore it)
→ uvicorn bci_mcp:app (streamable HTTP at /mcp, health at /health)
→ port 8000Repo files that matter for Manufact:
File | Purpose |
| Reproducible build ( |
| Exports |
| Documented deploy hints (reference only) |
| Alternative start script if you need it |
Troubleshooting
Symptom | Fix |
| Ensure |
| Pull latest |
| Start command must be HTTP ( |
| Clear both build and start commands to use auto-build, or clear start only to use the repo Dockerfile (stdio — not recommended for Manufact). |
Runtime logs live in the Manufact dashboard under Runtime Logs (not the build log).
Quickstart from source
Cloning the repo:
git clone https://github.com/enkhbold470/bci-mcp.git
cd bci-mcp
pip install -e ".[all,dev]"
bci-mcp stream --device synthetic://
bci-mcp dashboard # http://127.0.0.1:8000Record and replay:
bci-mcp record --device synthetic:// --seconds 30 --out session.npz
bci-mcp play session.npzNeurofeedback on one metric:
bci-mcp neurofeedback --device synthetic:// --metric focus --target 0.7Devices
One URI scheme for everything:
Device | URI | Extra install |
Synthetic (no hardware) |
| core |
NeuroFocus v4 (USB) |
|
|
NeuroFocus v4 (BLE) |
|
|
OpenBCI Cyton / Ganglion |
|
|
Muse 2 / S |
|
|
Any LSL stream |
|
|
Generic serial |
|
|
Recording replay |
| core |
Talk to Claude
Example after MCP is connected:
You: What's my focus level?
Claude: (calls get_brain_state) Focus 0.71, calm 0.32, attention 0.86. Signal looks good.
You: Run 60 seconds of neurofeedback on calm and tell me how I did.
Claude: (calls start_neurofeedback, then get_neurofeedback_score)
Mean calm 0.58, time in target 41%, best streak 9s.If you installed with pip install bci-mcp and want the binary directly in Desktop config:
{
"mcpServers": {
"bci-mcp": {
"command": "bci-mcp",
"args": ["serve"]
}
}
}Restart Claude after editing config. Check /mcp in Claude Code or the plug icon in Desktop.
MCP tools
Stdio server built with FastMCP (official MCP Python SDK).
Tools (14): list_devices, connect, disconnect, get_brain_state, get_band_powers, get_signal_quality, get_metric_definitions, get_pipeline_limitations, calibrate, record, start_neurofeedback, get_neurofeedback_score, mark_event, stream_summary
Resources: brain://state, brain://device, brain://citations
Prompt: interpret_brain_state
What's in the box
Part | What it does |
Devices | URI registry: synthetic, NeuroFocus, BrainFlow (OpenBCI/Muse), LSL, serial, playback |
MCP server | FastMCP over stdio. Drops into Claude Desktop / Code / Cursor |
DSP | Bandpass, notch, Welch band powers, focus/calm/attention/etc., signal quality |
CLI |
|
Extras | Web dashboard, neurofeedback trainer, record to CSV/npz/EDF, LSL publisher |
Tests | Hardware-free CI (synthetic, playback, in-process LSL). Python 3.10–3.14 |
How it fits together
EEG device -> Device (synthetic | neurofocus | brainflow | lsl | serial | playback)
| Chunk (channels x samples, microvolts)
v
Stream --> RingBuffer --> consumers
v
DSP Pipeline (filter -> band powers -> metrics -> quality)
| BrainState
+--> CLI / dashboard / neurofeedback / recorder / LSL
+--> MCP server --> Claude (or any MCP client)Install extras
From a clone:
pip install -e "." # core only (synthetic + MCP + CLI)
pip install -e ".[devices]" # OpenBCI, Muse, NeuroFocus, serial
pip install -e ".[lsl]" # Lab Streaming Layer
pip install -e ".[edf]" # EDF files
pip install -e ".[dashboard]" # web UI
pip install -e ".[all]" # everything aboveFrom PyPI: pip install bci-mcp (core) or install extras the same way with the package name instead of -e ".[...]".
Troubleshooting devices
Start with the synthetic device — if synthetic:// works, the MCP + DSP stack is fine and the problem is hardware or an extra.
Symptom | Likely cause / fix |
| The backend's extra isn't installed. Add it: |
| Device not plugged in, powered off, or claimed by another program. Close other EEG software and reconnect. |
Serial / OpenBCI: | Wrong port, or your user can't access it. Check |
Muse / NeuroFocus BLE won't connect | BLE is flaky — move closer, ensure the headset isn't paired to a phone, and retry. On Linux, BLE needs |
Signal quality stuck on | Electrodes not making contact (dry skin, hair, loose fit). Re-seat the headset; give it ~10 s to warm up before reading state. |
Claude connects but every tool returns | You haven't called |
| Normal — the pipeline needs ~0.5 s of samples. Read again in a moment. |
Over MCP, only synthetic, brainflow, lsl, and neurofocus URIs are allowed; playback:// and serial:// are rejected because they grant filesystem/device access to the client.
Security
EEG is biometric data, so the server treats every MCP tool argument and HTTP request as untrusted: recordings are sandboxed to BCI_RECORD_DIR, filesystem-touching device URIs (playback://, serial://) are refused over MCP, tool inputs are validated and capped, and the dashboard blocks cross-site WebSocket reads and DNS rebinding. Serving MCP over HTTP on a public host? Set MCP_AUTH_TOKEN and clients must send Authorization: Bearer <token>. Details and reporting: docs/security.md.
FAQ
How do you know what signal pattern means focus, calm, attention?
These are not guesses. Each metric is a ratio of EEG frequency band powers, taken from published research. A few examples:
focus= beta / (alpha + theta) — the Pope et al. (1995) engagement indexcalm= alpha / (alpha + beta) — alpha up, beta down, a long-known relaxation correlateattention= beta / theta — the inverse theta/beta ratio (Lubar 1991; Monastra 1999)
The full list, with every formula, the paper it comes from, and an honest caveat, lives in metrics.py. Claude can pull the same table at runtime with the get_metric_definitions tool, so it never has to invent what a number means. Each metric's sources come with DOIs, and the brain://citations resource returns them as JSON, along with the software's own citation and license. Sources that dispute a metric are tagged caveat so an agent can't cite them as support.
To be clear: these are proxies, not clinical measurements. Band-power ratios drift with electrode contact, eye movement, and jaw tension. Treat them as rough signals for demos and neurofeedback, and read the math in the source if you want to check it.
Aren't LLMs a bad fit for live EEG inference?
Yes, and this project does not do that. The language model does zero signal processing.
All the EEG math is plain, deterministic Python: notch filter, bandpass, Welch PSD, then the fixed band-power ratios above. Same input gives the same numbers every time, no model in the loop. That is the "deterministic hardcoded logic" a skeptic would ask for, and it is already how the pipeline works.
The LLM sits on top as a conversation layer. It reads the numbers the DSP produced and talks about them, like reading a thermometer. It never classifies raw EEG and never decides what counts as focus. So the split is: math in the code, words from the model.
Docs and accuracy
Docs: enkhbold470.github.io/bci-mcp
Questions about the code: DeepWiki. Agents: llms.txt.
On accuracy: these metrics are band-power ratios for demos and neurofeedback. Not clinical. Not diagnosis. Each formula is in the source if you want to check the math. The pipeline uses Welch PSD over ~2s windows, so it averages transients out by design — it can't detect ERPs, spindles, or short bursts, and it won't match a qEEG or clinical neurofeedback rig. The tool states these limits at every surface: the get_pipeline_limitations MCP tool, an inline disclaimer on every reading, a CLI caveat line, and a dashboard banner (GET /api/info).
Disclaimer: research and personal use only. Not a medical device.
Contributors
Who | Role |
@enkhbold470 (Enkhbold Ganbold) | Author and maintainer: design, NeuroFocus hardware integration, review, releases |
@agteo (Alex Teo) | Dashboard: first-steps tutorial (#18) and synthetic signal explorer (#19) |
How AI coding tools were used. Much of the June 2026 rewrite was written with AI coding
assistants (Claude Code, Cursor) working from design specs and plans that are kept in
docs/superpowers/. The maintainer directed that work, reviewed and tested the
changes, and is responsible for the code. The repository hook in .githooks/ removes AI
Co-authored-by trailers, so git log does not show which commits had AI help; this
paragraph is the disclosure.
Contributing
PRs welcome. See docs/contributing.md. Run ruff check src tests && pytest before you open one.
MIT. See LICENSE.
Available Tools
14 toolscalibrateC
Capture a baseline so focus/calm/etc. are personalized to the wearer.
Inputs: seconds, condition.
connectB
Connect to an EEG device and start streaming. Default is the synthetic brain.
Inputs: device_uri.
disconnectA
Disconnect from the current EEG device.
Inputs: no named parameters.
get_band_powersB
Get absolute and relative EEG band powers (delta, theta, alpha, beta, gamma).
Inputs: no named parameters.
get_brain_stateA
Get the current brain state. Returns heuristic band-power proxy metrics
(focus, calm, attention, engagement, fatigue, meditation), band powers, and
signal quality. Each reading carries confidence (0..1), per-metric
metric_confidence, and a status ('ok'/'warming_up'/'unreliable') — weight
the metrics by these and do not interpret an unreliable/low-confidence
reading. Call get_metric_definitions to learn what each metric means.
Inputs: no named parameters.
get_metric_definitionsA
Explain each brain metric: its exact formula, the literature it draws on
(with DOIs under references), and an honest caveat. Call this to learn what
focus/calm/attention/engagement/fatigue/meditation actually measure and how
much to trust them — they are heuristic proxies, not validated cognitive
measurements. Cite a reference only for its role: a caveat source
contests the metric and must never be cited as support.
Inputs: no named parameters.
get_neurofeedback_scoreA
Sample the current neurofeedback score (in-zone now + cumulative %).
Inputs: no named parameters.
get_pipeline_limitationsA
What this pipeline can and cannot do: the exact analysis method (Welch PSD window, band edges, filters), a plain-English list of limitations (it averages transients out, is not clinical/qEEG, metrics are heuristic proxies, no source localization/connectivity), and its intended use. Read this before drawing any conclusion from the metrics — especially do not present them as clinical, diagnostic, or event-level (ERP/spindle) results.
Inputs: no named parameters.
get_signal_qualityA
Get electrode signal quality, reading confidence, and detected artifacts (blink, railing, emg, flatline).
Inputs: no named parameters.
list_devicesA
List EEG devices/URIs you can connect to.
Inputs: no named parameters.
mark_eventC
Annotate the live stream with a labeled event marker.
Inputs: label (required).
recordB
Record the live stream for N seconds to a file (npz/csv/edf).
Inputs: fmt, path, seconds.
start_neurofeedbackC
Begin a neurofeedback session rewarding time spent above a metric target.
Inputs: metric, target.
stream_summaryB
Current brain-state snapshot. (The seconds window for rolling stats arrives in a
later phase; this currently returns the live reading.)
Inputs: seconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools target distinct actions, but get_brain_state, get_band_powers, get_signal_quality, and stream_summary overlap significantly because get_brain_state already bundles band powers, metrics, and signal quality. stream_summary is especially vague and its description admits it currently returns only the live reading, making it hard to distinguish from get_brain_state.
The set mostly follows a predictable snake_case pattern with clear verb/noun forms such as list_devices, get_brain_state, mark_event, and start_neurofeedback. Minor deviations are bare verbs like connect, disconnect, record, and calibrate, plus the noun-like stream_summary, but these remain readable and conventional for session lifecycle actions.
Fourteen tools is well-scoped for an EEG/BCI server that needs device lifecycle, signal inspection, calibration, events, recording, and neurofeedback. Each tool generally corresponds to a meaningful part of the live BCI workflow without excessive surface area.
The surface covers the core lifecycle: device discovery, connect/disconnect, signal and brain-state reads, calibration, event marking, recording, and neurofeedback start/score. Minor gaps remain, notably no explicit stop_neurofeedback or clear session-stop operation beyond disconnect, and marker/event retrieval is absent.
Maintenance
Related MCP Connectors
On-device human sensing for AI: EDNA ID continuity and live human context via MCP.
Real-time planetary signal engine and Model Context Protocol (MCP) server for autonomous AI agents.
Cross-device AI memory with encrypted activity capture and context handoff between AI tools
Your memory, everywhere AI goes. Build knowledge once, access it via MCP anywhere.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceFacilitates interaction and context sharing between AI models using the standardized Model Context Protocol (MCP) with features like interoperability, scalability, security, and flexibility across diverse AI systems.1-
- AlicenseNot gradedqualityNot gradedmaintenanceA bridging framework that integrates Knowledge Organization Infrastructure (KOI) with Model Context Protocol (MCP), enabling autonomous agents to exchange personality traits and expose capabilities as standardized tools.2MIT
- AlicenseNot gradedqualityDmaintenanceA Python framework that enables secure hardware control through the Model Context Protocol, allowing AI agents and automation systems to interact with physical devices across multiple platforms.5Apache 2.0
- AlicenseCqualityDmaintenanceIntegrates a bio-hybrid neuromorphic simulation pipeline with SNN, consciousness proxies, and bio-computing platform telemetry as MCP tools, resources, and prompts for AI assistants.482MIT