Metadata-Version: 2.4
Name: bci-mcp
Version: 0.1.3
Summary: Plug your brain into any AI — a real Model Context Protocol (MCP) server that streams live EEG brain state (focus, calm, attention) from any EEG device into Claude and any MCP client.
Project-URL: Homepage, https://github.com/enkhbold470/bci-mcp
Project-URL: Documentation, https://enkhbold470.github.io/bci-mcp/
Project-URL: Repository, https://github.com/enkhbold470/bci-mcp
Author: enkhbold470
License: MIT
License-File: LICENSE
Keywords: ai,bci,brain-computer-interface,brainflow,brainwave,claude,eeg,lsl,mcp,model-context-protocol,muse,neurofeedback,neuroscience,neurotech,openbci
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Requires-Dist: mcp>=1.2.0
Requires-Dist: numpy>=1.24
Requires-Dist: rich>=13.0
Requires-Dist: scipy>=1.10
Requires-Dist: typer>=0.12
Provides-Extra: all
Requires-Dist: bleak>=0.21; extra == 'all'
Requires-Dist: brainflow>=5.10; extra == 'all'
Requires-Dist: fastapi>=0.110; extra == 'all'
Requires-Dist: pyedflib>=0.1.36; extra == 'all'
Requires-Dist: pylsl>=1.16; extra == 'all'
Requires-Dist: pyserial>=3.5; extra == 'all'
Requires-Dist: uvicorn>=0.27; extra == 'all'
Requires-Dist: websockets>=12.0; extra == 'all'
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.110; extra == 'dashboard'
Requires-Dist: uvicorn>=0.27; extra == 'dashboard'
Requires-Dist: websockets>=12.0; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: devices
Requires-Dist: bleak>=0.21; extra == 'devices'
Requires-Dist: brainflow>=5.10; extra == 'devices'
Requires-Dist: pyserial>=3.5; extra == 'devices'
Provides-Extra: docs
Requires-Dist: mkdocs-shadcn>=0.11; extra == 'docs'
Requires-Dist: mkdocstrings-python>=1.10; extra == 'docs'
Requires-Dist: mkdocstrings>=0.25; extra == 'docs'
Requires-Dist: pygments>=2.17; extra == 'docs'
Requires-Dist: pymdown-extensions>=10; extra == 'docs'
Provides-Extra: edf
Requires-Dist: pyedflib>=0.1.36; extra == 'edf'
Provides-Extra: lsl
Requires-Dist: pylsl>=1.16; extra == 'lsl'
Description-Content-Type: text/markdown

<div align="center">

<img src="docs/assets/hero.svg" alt="BCI-MCP — stream live EEG brain state into Claude over the Model Context Protocol" width="100%">

# BCI-MCP

**Stream live EEG brain state — focus, calm, attention — into Claude and any MCP client. Works with no EEG hardware.**

Open-source [Model Context Protocol](https://modelcontextprotocol.io) server for brain-computer interface (BCI) data, for developers and neurotech tinkerers who want their AI assistant to read real-time brainwaves.

[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/enkhbold470/bci-mcp)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://enkhbold470.github.io/bci-mcp/)
[![CI](https://github.com/enkhbold470/bci-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/enkhbold470/bci-mcp/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-7c3aed)](https://modelcontextprotocol.io)
[![GitHub stars](https://img.shields.io/github/stars/enkhbold470/bci-mcp?style=social)](https://github.com/enkhbold470/bci-mcp/stargazers)
[![Last commit](https://img.shields.io/github/last-commit/enkhbold470/bci-mcp)](https://github.com/enkhbold470/bci-mcp/commits/main)

</div>

```
$ 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 it is](#what-it-is)
- [Quickstart (30 seconds)](#quickstart-30-seconds)
- [Install in one line](#install-in-one-line)
- [Any EEG device](#any-eeg-device)
- [Use it from Claude Desktop](#use-it-from-claude-desktop)
- [Use it from Claude Code](#use-it-from-claude-code)
- [MCP tools, resources, and prompt](#mcp-tools-resources-and-prompt)
- [What you get](#what-you-get)
- [Architecture](#architecture)
- [Install options](#install-options)
- [Use cases](#use-cases)
- [Why it exists](#why-it-exists)
- [Documentation](#documentation)
- [A note on accuracy](#a-note-on-accuracy)
- [Disclaimer](#disclaimer)
- [Contributing](#contributing)
- [License](#license)

## What it is

BCI-MCP is a small brain-computer interface toolkit built around one idea: read an EEG signal, turn it into a few honest real-time metrics, and make those available to an AI assistant through the Model Context Protocol.

The signal can come from an [OpenBCI](https://openbci.com) board, a [Muse](https://choosemuse.com) headband, a NeuroFocus device, any [Lab Streaming Layer (LSL)](https://labstreaminglayer.org) stream, a generic serial sensor, a recorded session, or a built-in synthetic generator that needs no hardware at all. Same code path for every source — so you can run the entire stack, including the live MCP server, before you own a headset.

## Quickstart (30 seconds)

```bash
pip install -e ".[all]"               # from a clone; "." alone gives core synthetic + MCP + CLI

bci-mcp stream --device synthetic://  # live terminal brain-meter, no hardware
bci-mcp dashboard                     # web dashboard at http://127.0.0.1:8000
```

That's it — you now have a running EEG brain-meter and a live MCP server, with zero hardware.

Record a session and replay it later:

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

Run a neurofeedback session that nudges a single metric toward a target:

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

## Install in one line

**Claude Code** (needs [Claude Code](https://code.claude.com/docs/en/mcp) + Node or uv):

```bash
claude mcp add bci-mcp -- npx -y bci-mcp
```

No Node? Python-only:

```bash
claude mcp add bci-mcp -- uvx bci-mcp serve
```

**Fully automatic** (picks npx → uvx → pip for you):

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

**Claude Desktop** — Settings → Developer → Edit Config:

```json
{
  "mcpServers": {
    "bci-mcp": {
      "command": "npx",
      "args": ["-y", "bci-mcp"]
    }
  }
}
```

**Cursor** — add to `~/.cursor/mcp.json` under `mcpServers`:

```json
"bci-mcp": { "command": "npx", "args": ["-y", "bci-mcp"] }
```

Then ask Claude: *“Connect to the demo brain — what’s my focus?”* No headset required.

> PyPI: `pip install bci-mcp` · npm launcher: `npx -y bci-mcp` (see `npm/bci-mcp` to publish)

## Any EEG device

One URI registry, one interface, every source:

| Device | URI | Install |
|---|---|---|
| Synthetic (no hardware) | `synthetic://` | core |
| NeuroFocus v4 (USB serial) | `neurofocus://serial/<port>` | `[devices]` |
| NeuroFocus v4 (BLE) | `neurofocus://ble/<name>` | `[devices]` |
| OpenBCI Cyton / Ganglion | `brainflow://cyton?serial_port=<port>` | `[devices]` |
| Muse 2 / S (via BrainFlow) | `brainflow://muse_s` | `[devices]` |
| Any LSL stream | `lsl://<name>` | `[lsl]` |
| Generic serial (1 int/line) | `serial://<port>` | `[devices]` |
| Recording replay | `playback://<file>` | core |

NeuroFocus v4 is supported over both serial and BLE, using the device's exact firmware UUIDs and counts-to-microvolt scaling.

## Use it from Claude Desktop

Add this to your Claude Desktop MCP config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "bci-mcp": {
      "command": "bci-mcp",
      "args": ["serve"]
    }
  }
}
```

Restart Claude Desktop, then talk to your brain data in plain language. An example exchange:

```
You:    What's my current focus level?
Claude: (calls get_brain_state) -> Your focus is 0.71 and rising, calm is
        0.32, attention 0.86, signal quality GOOD. You look engaged and alert.

You:    Run a 60-second neurofeedback session targeting calm and tell me how I did.
Claude: (calls start_neurofeedback, then get_neurofeedback_score)
        -> Session done. Mean calm 0.58, time-in-target 41%, best streak 9s.
```

The synthetic device means this works the moment you install — no headset required to wire up and test the MCP integration.

## Use it from Claude Code

```bash
claude mcp add bci-mcp -- npx -y bci-mcp
```

Python only (no Node):

```bash
claude mcp add bci-mcp -- uvx bci-mcp serve
```

If you already ran `pip install bci-mcp`:

```bash
claude mcp add bci-mcp -- bci-mcp serve
```

Check it connected with `claude mcp list` or `/mcp` inside a session. Share with the team via `.mcp.json` using `--scope project`.

## MCP tools, resources, and prompt

Built on the official MCP Python SDK (FastMCP) over stdio.

- **Tools:** `list_devices`, `connect`, `disconnect`, `get_brain_state`, `get_band_powers`, `get_signal_quality`, `calibrate`, `record`, `start_neurofeedback`, `get_neurofeedback_score`, `mark_event`, `stream_summary`
- **Resources:** `brain://state`, `brain://device`
- **Prompt:** `interpret_brain_state`

## What you get

| Area | What's included |
|---|---|
| Device layer | One URI registry across synthetic, NeuroFocus (serial + BLE), OpenBCI and Muse via BrainFlow, LSL, generic serial, and recording playback |
| MCP server | Real server on the official MCP SDK (FastMCP), stdio transport, drops straight into Claude Desktop |
| DSP pipeline | Bandpass + notch filtering, Welch band powers (delta / theta / alpha / beta / gamma), derived metrics (focus, calm, attention, engagement, fatigue, meditation), signal-quality and artifact checks, optional per-person calibration |
| CLI (`bci-mcp`) | `devices`, `stream`, `record`, `play`, `neurofeedback`, `dashboard`, `serve` |
| Tooling | Terminal brain-meter, FastAPI web dashboard, neurofeedback trainer, session recording (CSV / npz / EDF) with replay, LSL publisher |
| Quality | 81 hardware-free tests (synthetic device, playback, in-process LSL, BrainFlow synthetic board), ruff clean, CI on Python 3.10-3.12, MIT licensed |

## Architecture

```
EEG device -> Device (synthetic | neurofocus | brainflow | lsl | serial | playback)
                 |  Chunk (channels x samples, microvolts)
                 v
              Stream --> RingBuffer --> consumers
                 v
            DSP Pipeline  (bandpass/notch -> Welch band powers -> metrics -> quality)
                 |  BrainState (focus, calm, attention, ..., signal quality)
                 +--> CLI brain-meter / web dashboard
                 +--> neurofeedback trainer
                 +--> recorder (CSV / npz / EDF)  <-->  PlaybackDevice
                 +--> LSL publisher
                 +--> MCP server (FastMCP, stdio)  -->  Claude / any MCP client
```

## Install options

```bash
pip install -e "."              # core: numpy, scipy, mcp, typer, rich (synthetic + MCP + CLI)
pip install -e ".[devices]"     # + brainflow, bleak, pyserial (OpenBCI, Muse, NeuroFocus, serial)
pip install -e ".[lsl]"         # + pylsl (consume / publish Lab Streaming Layer)
pip install -e ".[edf]"         # + pyedflib (EDF recording)
pip install -e ".[dashboard]"   # + fastapi, uvicorn (web dashboard)
pip install -e ".[all]"         # everything
```

## Use cases

- Give Claude live context about your focus, calm, or fatigue while you work or study.
- Build neurofeedback experiments without writing your own DSP or device drivers.
- Prototype an EEG / BCI app against the synthetic device, then swap in real hardware via a URI change.
- Record EEG sessions to CSV / npz / EDF and replay them deterministically in tests or demos.
- Publish a processed brain state over LSL for other lab tools to consume.
- Teach signal processing and brain-computer interface concepts with a runnable, hardware-free stack.

## Why it exists

Most EEG tooling assumes you already own a specific headset and want raw samples or a heavy GUI. BCI-MCP takes a narrower, more practical position:

- **Hardware-optional.** The synthetic device runs the full pipeline and a real MCP server with nothing plugged in. Most BCI projects can't be tried until hardware arrives.
- **Device-agnostic by URI.** OpenBCI, Muse, NeuroFocus, LSL, serial, and playback all share one interface, instead of one SDK per vendor.
- **Built for AI assistants.** The output is an MCP server, not just a plotting window — so any MCP client, Claude included, can read and act on brain state.
- **Honest, readable metrics.** Plain band-power ratios documented in the source, not opaque "scores."

## Documentation

Full docs: **https://enkhbold470.github.io/bci-mcp/** (MkDocs, shadcn theme)

For AI Q&A about the codebase, use [DeepWiki](https://deepwiki.com/enkhbold470/bci-mcp). Agents can also read [`llms.txt`](https://enkhbold470.github.io/bci-mcp/llms.txt) for a curated doc index.

[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://enkhbold470.github.io/bci-mcp/)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/enkhbold470/bci-mcp)

## A note on accuracy

The metrics here are simple, well-understood band-power ratios, not clinical measures. They are useful for neurofeedback, demos, and experimentation, and each one is documented in the source so you can see exactly how it is computed.

## Disclaimer

BCI-MCP is for research, education, and personal experimentation. It is not a medical device and must not be used for diagnosis or treatment.

## Contributing

Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Good first issues are labeled [`good first issue`](https://github.com/enkhbold470/bci-mcp/labels/good%20first%20issue). Please run `ruff check src tests && pytest` before opening a PR.

If this project is useful to you, a star helps others find it.

## License

MIT — see [LICENSE](LICENSE).

## Star history

[![Star History Chart](https://api.star-history.com/svg?repos=enkhbold470/bci-mcp&type=Date)](https://star-history.com/#enkhbold470/bci-mcp&Date)

---

<sub>Topics: EEG · BCI · brain-computer interface · Model Context Protocol · MCP · Claude · neurofeedback · OpenBCI · Muse · BrainFlow · LSL · Lab Streaming Layer · NeuroFocus · brainwave · neurotech · neuroscience · real-time signal processing · band power · alpha/beta/theta · focus tracking · Python</sub>
