Skip to main content
Glama

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.

Ask DeepWiki Docs CI PyPI npm Python License: MIT MCP Glama Listed on mcpservers.org GitHub stars Last commit

$ bci-mcp stream --device synthetic://

  FOCUS        ##############......  0.71
  CALM         ######..............  0.32
  ATTENTION    #################...  0.86
  ENGAGEMENT   ##############......  0.70
  alpha ####  beta #######  theta ##  delta #  gamma ###     signal: GOOD

Contents

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)

  • OpenBCI, Muse via BrainFlow

  • 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_neurofeedback on 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-mcp

No Node? Use Python:

claude mcp add bci-mcp -- uvx bci-mcp serve

Or let the install script pick for you:

curl -fsSL https://raw.githubusercontent.com/enkhbold470/bci-mcp/main/scripts/install-mcp.sh | bash

Claude 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

  1. Go to manufact.com/cloud and sign in.

  2. New server → Deploy from GitHub.

  3. Select this repo: enkhbold470/bci-mcp, branch main.

  4. 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 8000

2. 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

8000

Build command

(leave empty)

Start command

(leave empty) — Manufact auto-starts uvicorn bci_mcp:app

If auto-detect fails, set the start command explicitly:

uvicorn bci_mcp:app --host 0.0.0.0 --port 8000

Do 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/mcp

4. 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 8000

Repo files that matter for Manufact:

File

Purpose

uv.lock

Reproducible build (uv sync --frozen)

bci_mcp/__init__.py

Exports app for uvicorn bci_mcp:app

manufact.toml

Documented deploy hints (reference only)

scripts/manufact-start.sh

Alternative start script if you need it

Troubleshooting

Symptom

Fix

Unable to find lockfile at uv.lock

Ensure uv.lock is committed and not listed in .dockerignore.

Attribute "app" not found in module "bci_mcp"

Pull latest main — app must be exported from bci_mcp.

Server crashed / port 8000 not open

Start command must be HTTP (uvicorn bci_mcp:app …), not bci-mcp serve.

Found Dockerfile but buildCommand/startCommand are set

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:8000

Record and replay:

bci-mcp record --device synthetic:// --seconds 30 --out session.npz
bci-mcp play session.npz

Neurofeedback on one metric:

bci-mcp neurofeedback --device synthetic:// --metric focus --target 0.7

Devices

One URI scheme for everything:

Device

URI

Extra install

Synthetic (no hardware)

synthetic://

core

NeuroFocus v4 (USB)

neurofocus://serial/<port>

[devices]

NeuroFocus v4 (BLE)

neurofocus://ble/<name>

[devices]

OpenBCI Cyton / Ganglion

brainflow://cyton?serial_port=<port>

[devices]

Muse 2 / S

brainflow://muse_s

[devices]

Any LSL stream

lsl://<name>

[lsl]

Generic serial

serial://<port>

[devices]

Recording replay

playback://<file>

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

devices, stream, record, play, neurofeedback, dashboard, serve

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 above

From 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

ImportError / ModuleNotFoundError on brainflow, bleak, pyserial, pylsl, pyedflib

The backend's extra isn't installed. Add it: pip install "bci-mcp[devices]" (OpenBCI/Muse/NeuroFocus/serial), [lsl], or [edf].

bci-mcp devices shows schemes but finds no hardware

Device not plugged in, powered off, or claimed by another program. Close other EEG software and reconnect.

Serial / OpenBCI: could not open port or permission denied

Wrong port, or your user can't access it. Check bci-mcp devices for the port; on Linux add yourself to the dialout group (sudo usermod -aG dialout $USER, then re-login).

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 bluez running.

Signal quality stuck on poor / metrics look flat

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 {"error": ...}

You haven't called connect yet. Ask Claude to connect to a device (e.g. the demo brain) first.

warming_up on the first read

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 index

  • calm = alpha / (alpha + beta) — alpha up, beta down, a long-known relaxation correlate

  • attention = 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.

Star History Chart

Available Tools

14 tools
calibrateC

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

    B3.4/5.0

    Scored across 14 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessMixed handling

    Related MCP Connectors

    Related MCP Servers