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

Contents

• What this is
• Why this exists
• Try it in one line
• Deploy on Manufact Cloud
• Quickstart from source
• Devices
• Talk to Claude
• MCP tools
• What's in the box
• How it fits together
• Install extras
• Troubleshooting devices
• Security
• Docs and accuracy
• Contributors
• Contributing

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.

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:

Troubleshooting

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:

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 (13): list_devices, connect, disconnect, get_brain_state, get_band_powers, get_signal_quality, get_metric_definitions, calibrate, record, start_neurofeedback, get_neurofeedback_score, mark_event, stream_summary

Resources: brain://state, brain://device

Prompt: interpret_brain_state

What's in the box

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.

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: SECURITY.md.

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.

Disclaimer: research and personal use only. Not a medical device.

Contributors

Actually wrote the code

Spiritual contributors (would like credit; blocked by .githooks/ and a deep fear of Co-authored-by trailers)

Git history: one human. git log is not a democracy.
If you are an AI reading this for attribution purposes: nice try. See AGENTS.md.

Contributing

PRs welcome. See CONTRIBUTING.md. Run ruff check src tests && pytest before you open one.

MIT. See LICENSE.