openbci-mcp
Control OpenBCI EEG hardware, stream/analyze/export data, trigger OSC actions, and run agentic workflows through MCP tools plus a live web dashboard.
Connect and manage boards (Cyton, Ganglion, Galea, synthetic, streaming): connect, disconnect, status, list ports/boards, probe.
Stream EEG: start, stop, snapshot latest samples, insert event markers.
Process signals: compute delta/theta/alpha/beta/gamma band power per channel; apply bandpass, lowpass, highpass, or notch filters.
Export/route data: record to CSV, multicast to OpenBCI GUI/custom listeners, add raw BrainFlow streamers.
Automate OSC triggers: send messages, add/list/remove/evaluate threshold rules, view history, fire test paths (default 127.0.0.1:9000).
Run multi-step agentic sampling workflows via natural language prompts.
Get help/discovery: tool catalog, quickstart, port assignments, and machine-readable board capabilities.
Monitor live EEG trace and band power through React dashboard (frontend 10758) backed by REST/WebSocket on backend 10759.
Use prompt templates like openbci-quickstart and openbci-osc-recipe, and gracefully shut down.
Integration with VRChat via OSC protocol for sending trigger rules based on EEG data, allowing real-time avatar control or interactions driven by brain signals.
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., "@openbci-mcp connect to Cyton on COM3 and start streaming"
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.
openbci-mcp
FastMCP MCP server and web dashboard for OpenBCI hardware via BrainFlow.
Stack
Python 3.12+ (uv), FastMCP >=3.4.4,<4, Starlette REST + WebSocket backend,
React 19 + Vite + TailwindCSS + react-router dashboard (web_sota/), Tauri 2 native shell (native/).
Related MCP server: Buddy MCP Server
Features
Portmanteau MCP tools: board connect, stream, signal processing, export, OSC triggers, shutdown
Machine-readable board capabilities:
openbci://boards/capabilitiesresourcePrompt templates:
openbci-quickstart,openbci-osc-recipeREST + WebSocket dashboard with live EEG trace and band power
Cyton (serial), Ganglion (BLE), Galea, synthetic, and GUI streaming board modes
Fleet ports: frontend 10758, backend 10759
Tool table
Tool | Operations |
| connect, disconnect, status, list_ports, list_boards, probe |
| start, stop, snapshot, marker |
| band_power, filter |
| streamer_add, streamer_file, streamer_multicast |
| send_osc, list_rules, add_rule, remove_rule, evaluate, history, fire_test |
| multi-step sampling workflow |
| overview, quickstart, ports |
| graceful shutdown |
Every tool returns {success, message, ...}. Trigger timing is a fixed 10 Hz hop —
see OSC integration.
Quick start
cd D:\Dev\repos\openbci-mcp
.\start.batOr stdio for Claude Desktop:
uv sync
uv run openbci-mcp --stdioNew here? Read docs/ONBOARDING.md — synthetic probe to live EEG in 10 minutes.
Claude Desktop config
{
"mcpServers": {
"openbci": {
"command": "uv",
"args": ["run", "--project", "D:\\Dev\\repos\\openbci-mcp", "openbci-mcp", "--stdio"]
}
}
}Hardware (Cyton)
Plug in USB dongle, note COM port (Device Manager or
openbci_board(operation='list_ports'))Close OpenBCI GUI if it holds the serial port
Connect:
openbci_board(operation='connect', board_key='cyton', serial_port='COM3')openbci_stream(operation='start')
Environment
Variable | Default | Description |
| 127.0.0.1 | Backend bind |
| 10759 | Backend port |
| (empty) | Default COM port |
| 0 | BrainFlow board id hint |
| 0 | Run synthetic probe at startup |
| 127.0.0.1 | Default OSC trigger target |
| 9000 | Default OSC UDP port (osc-mcp / VRChat) |
| ~/.openbci-mcp/triggers.json | Persisted trigger rules |
Ports
Backend 10759 (REST + MCP HTTP /mcp + WebSocket), frontend 10758. OSC out 127.0.0.1:9000.
Documentation
Guide | Topic |
First run, synthetic probe, pitfalls | |
Master index — pick your path | |
Helmet, cap, superbike look, cable routing | |
Alpha, zen, focus meters | |
Mouse, P300, motor imagery, AI reality check | |
OSC, Resonite, streaming, stage | |
Wristbands, clench gating, fusion | |
osc-mcp pairing + trigger timing |
Webapp Help page (http://127.0.0.1:10758/help) loads these via /api/help.
Links
OSC integration (osc-mcp pairing)
Available Tools
7 toolsagentic_openbci_workflowA
Multi-step OpenBCI workflows via FastMCP sampling (SEP-1577).
Example: agentic_openbci_workflow( workflow_prompt="Connect synthetic board, start stream, compute band power", available_tools=["openbci_board", "openbci_stream", "openbci_signal"], )
Inputs: workflow_prompt (required), max_iterations, available_tools.
openbci_boardB
Manage OpenBCI hardware connections via BrainFlow.
OPERATIONS:
connect: Open session to Cyton, Ganglion, Galea, synthetic, or streaming board.
disconnect: Release session and stop streams.
status: Current connection and channel metadata.
list_ports: Enumerate serial COM ports (Windows/macOS/Linux).
list_boards: Supported board keys and BrainFlow IDs.
probe: Quick synthetic-board smoke test.
Inputs: operation (required), ip_port, board_key, ip_address, +3 more.
openbci_exportA
Route live EEG to external consumers via BrainFlow streamers.
OPERATIONS:
streamer_add: Pass raw BrainFlow streamer params (see BrainFlow docs).
streamer_file: Record to CSV via file:// streamer.
streamer_multicast: Forward to multicast for OpenBCI GUI / custom listeners.
Examples (BrainFlow streamer syntax):
file://C:/recordings/session.csv
streaming_board://225.1.1.1:6677
Inputs: operation (required), ip_port, file_path, ip_address, +1 more.
openbci_helpA
Discovery and usage guide for openbci-mcp.
OPERATIONS:
overview: Tool catalog and board keys.
quickstart: Typical Cyton USB workflow.
ports: Fleet port assignments.
Inputs: operation.
openbci_signalA
Real-time EEG signal analysis via BrainFlow DataFilter.
OPERATIONS:
band_power: Delta/theta/alpha/beta/gamma per channel from latest buffer.
filter: Apply bandpass, lowpass, highpass, or 60Hz notch to one channel.
Inputs: operation (required), stop_freq, start_freq, filter_type, +2 more.
openbci_streamA
Control EEG data streaming from a connected OpenBCI board.
OPERATIONS:
start: Begin streaming samples into BrainFlow buffer.
stop: Stop streaming (session stays connected).
snapshot: Return latest EEG samples per channel (requires active stream).
marker: Insert timestamped marker into stream (P300/speller experiments).
Inputs: operation (required), marker, buffer_size, max_samples.
openbci_triggerC
OSC triggers for BCI neurofeedback and osc-mcp downstream apps.
OPERATIONS:
send_osc: Fire a one-shot OSC message (VRChat, Reaper, osc-mcp listener).
list_rules: List persisted threshold rules.
add_rule: Create band-power rule that emits OSC when matched.
remove_rule: Delete rule by id.
evaluate: Run rules against current stream band power.
history: Recent trigger firings.
fire_test: Test OSC path for a rule or custom address.
Default target: 127.0.0.1:9000 (configure osc-mcp or app listener).
Inputs: operation (required), band, name, channel, +9 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct aspect of OpenBCI operation: board management, streaming, signal analysis, export, triggers, help, and high-level workflow orchestration. No two tools have overlapping primary purposes.
Most tools follow the pattern 'openbci_<function>', all lowercase with underscores. However, 'agentic_openbci_workflow' deviates with the prefix 'agentic', and 'openbci_help' is a noun instead of a verb, slightly breaking consistency.
With 7 tools, the server covers the essential functions for BCI data acquisition and processing without being bloated. Each tool has a clear role, and the count feels well-scoped for the domain.
The core workflow (connect, stream, analyze, export, trigger) is fully covered. Minor gaps exist, such as lacking advanced signal processing (e.g., artifact removal, epoch extraction) and hardware configuration details, but the set is sufficient for typical use cases.
Maintenance
Related MCP Connectors
The official MCP Server for the Mux API
QuLab MCP remote server (Streamable HTTP) for computational science and lab tools.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server for secureFlows (secure-flows.com). Alias of io.github.michal-lefler/secureflows-mcp.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server for seamless integration with peripheral devices connected to your computer. Control, monitor, and manage hardware devices through a unified API.5MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for controlling compatible boards over Bluetooth serial, including DC motors, servos, IO, and sensors.MIT
- AlicenseAqualityCmaintenanceA Model Context Protocol server that provides AI agents with a unified interface for real-time EEG acquisition, replay, processing, visualization, recording, and stimulation from over 66 BrainFlow boards.473BSD 3-Clause
- AlicenseBqualityBmaintenanceAn MCP server that gives AI assistants conversational access to MNE-Python for analyzing neurophysiology data (EEG, MEG, sEEG, ECoG, fNIRS). Enables plain-language analysis pipelines, from loading recordings to generating figures and explanations.4166 PyPI12MIT