MCP for Brain Computer Interface

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

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

---

Contenido

• Qué es esto
• Por qué existe
• Pruébalo en una línea
• Despliega en Manufact Cloud
• Inicio rápido desde el código fuente
• Dispositivos
• Habla con Claude
• Herramientas MCP
• Qué incluye
• Cómo encaja todo
• Instalar extras
• Solución de problemas con dispositivos
• Seguridad
• Preguntas frecuentes
• Documentación y precisión
• Colaboradores
• Contribuir

Qué es esto

Tienes una señal EEG. Esto la convierte en números que Claude puede leer: enfoque, calma, atención, potencias de banda, calidad de señal. Básicamente, un pequeño servidor de interfaz cerebro-computadora que no estorba.

¿Aún no tienes casco? Usa el cerebro simulado integrado (synthetic://). Mismo código que el hardware real. Puedes probar toda la pila MCP antes de comprar nada.

Fuentes que funcionan hoy:

• Demo sintética (sin hardware)
• OpenBCI, Muse vía BrainFlow
• NeuroFocus (serial o BLE)
• Flujos LSL
• Serial genérico
• Sesiones grabadas (reproducción desde archivo)

Por qué existe

Los LLM ya pueden leer tu pantalla y tu código. No pueden leerte a ti. Esto cierra esa brecha con la única señal fisiológica que el hardware de consumo maneja razonablemente bien — el EEG — y se la entrega a Claude como números simples que puede razonar. Concretamente, la gente lo usa para:

• Neurofeedback con un entrenador. Ejecuta start_neurofeedback sobre enfoque o calma y deja que Claude lea la puntuación, explique la tendencia y ajuste la sesión — en lugar de mirar un gráfico de barras solo.
• Asistentes conscientes del estado. Un agente que puede notar que tu atención se desvanece puede resumir en lugar de extenderse, o sugerir un descanso. El enfoque, la calma y la atención llegan como números que cualquier cliente MCP puede usar.
• Accesibilidad. Un front-end de modelo de lenguaje para señales cerebrales para usuarios con discapacidad motora, donde una llamada a herramienta sustituye a un clic.
• Investigación y prototipado. Un esquema URI cubre OpenBCI, Muse, LSL, serial y reproducción de archivos, así que un experimento escrito contra synthetic:// se ejecuta sin cambios en hardware real. La grabación y reproducción hacen que las sesiones sean reproducibles.

No es clínico, no es diagnóstico — son ratios de potencia de banda para demos, neurofeedback e investigación (ver Documentación y precisión).

Pruébalo en una línea

Claude Code

claude mcp add bci-mcp -- npx -y bci-mcp

¿No tienes Node? Usa Python:

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

O deja que el script de instalación elija por ti:

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

Claude Desktop (Configuración → Desarrollador → Editar configuración):

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

Cursor (~/.cursor/mcp.json, bajo mcpServers):

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

Luego pregunta algo como: Conéctate al cerebro de demostración. ¿Cuál es mi enfoque ahora mismo?

Paquetes publicados: pip install bci-mcp (PyPI) y npx -y bci-mcp (npm).

Despliega en Manufact Cloud

Aloja un endpoint MCP público en Manufact Cloud (anteriormente mcp-use). Sin servidor que gestionar — Manufact compila desde GitHub y te da una URL como https://your-server.run.mcp-use.com/mcp.

1. Despliega desde GitHub

1. Ve a manufact.com/cloud e inicia sesión.
2. Nuevo servidor → Desplegar desde GitHub.
3. Selecciona este repositorio: enkhbold470/bci-mcp, rama main.
4. Manufact detecta Python y la pila FastMCP automáticamente.

O usa la CLI (después de npm i -g mcp-use y mcp-use login):

git push origin main   # Manufact builds from GitHub, not your laptop
mcp-use deploy --runtime python --port 8000

2. Configuración del panel (importante)

Usa estos valores en el formulario de despliegue de Manufact. Equivocarse con los comandos de compilación/inicio es el modo de fallo más común.

Configuración	Valor
Puerto	8000
Comando de compilación	(déjalo vacío)
Comando de inicio	(déjalo vacío) — Manufact inicia uvicorn bci_mcp:app automáticamente

Si la detección automática falla, establece el comando de inicio explícitamente:

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

No establezcas un comando de compilación personalizado como uv sync — Manufact lo ejecuta por ti.
No uses bci-mcp serve solo — ese es el modo stdio para Claude Desktop y no escuchará en el puerto 8000.

3. Verifica el despliegue

Después de que la compilación tenga éxito, verifica:

curl https://YOUR-SLUG.run.mcp-use.com/health
# → {"status":"healthy"}

Tu endpoint MCP:

https://YOUR-SLUG.run.mcp-use.com/mcp

4. Conecta un cliente MCP

Claude Desktop / Cursor — añade un servidor MCP remoto (HTTP streamable):

{
  "mcpServers": {
    "bci-mcp-cloud": {
      "url": "https://YOUR-SLUG.run.mcp-use.com/mcp"
    }
  }
}

Luego pregunta: Conéctate al cerebro de demostración — ¿cuál es mi enfoque?
El servidor en la nube usa el dispositivo sintético por defecto (no se requiere casco).

Qué ejecuta Manufact internamente

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

Archivos del repositorio que importan para Manufact:

Archivo	Propósito
uv.lock	Compilación reproducible (uv sync --frozen)
bci_mcp/__init__.py	Exporta app para uvicorn bci_mcp:app
manufact.toml	Sugerencias de despliegue documentadas (solo referencia)
scripts/manufact-start.sh	Script de inicio alternativo si lo necesitas

Solución de problemas

Síntoma	Solución
Unable to find lockfile at uv.lock	Asegúrate de que uv.lock esté confirmado y no listado en .dockerignore.
Attribute "app" not found in module "bci_mcp"	Actualiza el último main — app debe exportarse desde bci_mcp.
Server crashed / puerto 8000 no abierto	El comando de inicio debe ser HTTP (uvicorn bci_mcp:app …), no bci-mcp serve.
Found Dockerfile but buildCommand/startCommand are set	Limpia ambos comandos de compilación e inicio para usar la compilación automática, o limpia solo el de inicio para usar el Dockerfile del repositorio (stdio — no recomendado para Manufact).

Los registros de ejecución viven en el panel de Manufact bajo Registros de ejecución (no el registro de compilación).

Inicio rápido desde el código fuente

Clonando el repositorio:

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

Grabar y reproducir:

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

Neurofeedback en una métrica:

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

Dispositivos

Un esquema URI para todo:

Dispositivo	URI	Instalación extra
Sintético (sin hardware)	synthetic://	núcleo
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]
Cualquier flujo LSL	lsl://<name>	[lsl]
Serial genérico	serial://<port>	[devices]
Reproducción de grabación	playback://<file>	núcleo

Habla con Claude

Ejemplo después de conectar MCP:

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.

Si instalaste con pip install bci-mcp y quieres el binario directamente en la configuración de Desktop:

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

Reinicia Claude después de editar la configuración. Verifica /mcp en Claude Code o el ícono de enchufe en Desktop.

Herramientas MCP

Servidor stdio construido con FastMCP (SDK oficial de Python para MCP).

Herramientas (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

Recursos: brain://state, brain://device

Prompt: interpret_brain_state

Qué incluye

Parte	Qué hace
Dispositivos	Registro URI: sintético, NeuroFocus, BrainFlow (OpenBCI/Muse), LSL, serial, reproducción
Servidor MCP	FastMCP sobre stdio. Se integra en Claude Desktop / Code / Cursor
DSP	Paso de banda, notch, potencias de banda Welch, enfoque/calma/atención/etc., calidad de señal
CLI	devices, stream, record, play, neurofeedback, dashboard, serve
Extras	Panel web, entrenador de neurofeedback, grabación a CSV/npz/EDF, publicador LSL
Pruebas	CI sin hardware (sintético, reproducción, LSL en proceso). Python 3.10–3.12

Cómo encaja todo

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)

Instalar extras

Desde un clon:

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

Desde PyPI: pip install bci-mcp (núcleo) o instala extras de la misma manera con el nombre del paquete en lugar de -e ".[...]".

Solución de problemas con dispositivos

Empieza con el dispositivo sintético — si synthetic:// funciona, la pila MCP + DSP está bien y el problema es el hardware o un extra.

Síntoma	Causa probable / solución
ImportError / ModuleNotFoundError en brainflow, bleak, pyserial, pylsl, pyedflib	El extra del backend no está instalado. Añádelo: pip install "bci-mcp[devices]" (OpenBCI/Muse/NeuroFocus/serial), [lsl], o [edf].
bci-mcp devices muestra esquemas pero no encuentra hardware	El dispositivo no está enchufado, apagado o está siendo usado por otro programa. Cierra otro software EEG y reconecta.
Serial / OpenBCI: could not open port o permiso denegado	Puerto incorrecto, o tu usuario no puede acceder. Verifica bci-mcp devices para el puerto; en Linux añádete al grupo dialout (sudo usermod -aG dialout $USER, luego vuelve a iniciar sesión).
Muse / NeuroFocus BLE no conecta	BLE es inestable — acércate, asegúrate de que el casco no esté emparejado con un teléfono, y reintenta. En Linux, BLE necesita bluez ejecutándose.
Calidad de señal atascada en poor / métricas planas	Los electrodos no hacen contacto (piel seca, cabello, ajuste flojo). Recoloca el casco; dale ~10 s para calentarse antes de leer el estado.
Claude conecta pero cada herramienta devuelve {"error": ...}	Aún no has llamado a connect. Pide a Claude que se conecte a un dispositivo (por ejemplo, el cerebro de demostración) primero.
warming_up en la primera lectura	Normal — la tubería necesita ~0.5 s de muestras. Lee de nuevo en un momento.

Sobre MCP, solo se permiten URIs synthetic, brainflow, lsl y neurofocus; playback:// y serial:// se rechazan porque otorgan acceso a archivos/dispositivos al cliente.

Seguridad

El EEG es datos biométricos, así que el servidor trata cada argumento de herramienta MCP y solicitud HTTP como no confiable: las grabaciones están aisladas en BCI_RECORD_DIR, los URIs de dispositivos que tocan el sistema de archivos (playback://, serial://) se rechazan sobre MCP, las entradas de herramientas se validan y limitan, y el panel bloquea lecturas WebSocket entre sitios y el rebinding de DNS. ¿Sirviendo MCP sobre HTTP en un host público? Establece MCP_AUTH_TOKEN y los clientes deben enviar Authorization: Bearer <token>. Detalles e informes: docs/security.md.

Preguntas frecuentes

¿Cómo sabes qué patrón de señal significa enfoque, calma, atención?

No son suposiciones. Cada métrica es un ratio de potencias de banda de frecuencia EEG, tomado de investigación publicada. Algunos ejemplos:

• focus = beta / (alpha + theta) — el índice de compromiso de Pope et al. (1995)
• calm = alpha / (alpha + beta) — alpha arriba, beta abajo, un correlato de relajación conocido desde hace tiempo
• attention = beta / theta — el ratio inverso theta/beta (Lubar 1991; Monastra 1999)

La lista completa, con cada fórmula, el artículo del que proviene y una advertencia honesta, vive en metrics.py. Claude puede extraer la misma tabla en tiempo de ejecución con la herramienta get_metric_definitions, así que nunca tiene que inventar lo que significa un número.

Para ser claros: son proxies, no mediciones clínicas. Los ratios de potencia de banda varían con el contacto de los electrodos, el movimiento ocular y la tensión mandibular. Trátalos como señales aproximadas para demos y neurofeedback, y lee las matemáticas en el código fuente si quieres verificarlas.

¿No son los LLM una mala opción para la inferencia EEG en vivo?

Sí, y este proyecto no hace eso. El modelo de lenguaje hace cero procesamiento de señales. Toda la matemática del EEG es Python simple y determinista: filtro notch, paso de banda, PSD de Welch, y luego las proporciones fijas de potencia de banda mencionadas arriba. La misma entrada produce los mismos números cada vez, sin modelo en el bucle. Eso es la "lógica fija determinista" que un escéptico pediría, y ya es así como funciona el pipeline.

El LLM se sitúa encima como una capa de conversación. Lee los números que produjo el DSP y habla sobre ellos, como leer un termómetro. Nunca clasifica EEG crudo ni decide qué cuenta como concentración. Así que la división es: matemáticas en el código, palabras del modelo.

Documentación y precisión

Documentación: enkhbold470.github.io/bci-mcp

Preguntas sobre el código: DeepWiki. Agentes: llms.txt.

Sobre la precisión: estas métricas son proporciones de potencia de banda para demos y neurofeedback. No son clínicas. No son diagnóstico. Cada fórmula está en el código fuente si quieres verificar las matemáticas. El pipeline usa PSD de Welch en ventanas de ~2 segundos, por lo que promedia los transitorios por diseño: no puede detectar ERPs, husos del sueño ni ráfagas cortas, y no coincidirá con un qEEG o un equipo clínico de neurofeedback. La herramienta declara estos límites en cada superficie: la herramienta MCP get_pipeline_limitations, un disclaimer en línea en cada lectura, una línea de advertencia en la CLI y un banner en el panel (GET /api/info).

Aviso legal: solo para investigación y uso personal. No es un dispositivo médico.

Contribuyentes

Realmente escribieron el código

Quién	Rol
@enkhbold470	Humano. Commits, culpa, culpa del EEG.

Contribuyentes espirituales (querrían crédito; bloqueados por .githooks/ y un miedo profundo a los avances de Co-authored-by)

Agente	Vibra
Claude	Leyó el estado cerebral. Juzgó la puntuación de concentración. Hizo preguntas de seguimiento de todos modos.
Cursor Agent	Escribió la mitad del Dockerfile a las 2 a. m. Lo niega.
Devin	Programado para 47 tickets de Jira sobre este repositorio. No ha fichado.
GitHub Copilot	Oráculo de autocompletado. Una vez sugirió import brain.
OpenAI Codex	Duende de terminal. Abriría un PR titulado "arreglar arreglar arreglar".
Google Jules	Asíncrono. Muy asíncrono. Sigue pensando en el PR.
Aider	Entusiasta de /commit. Opiniones firmes sobre uv.lock.
OpenHands (antes OpenDevin)	Trajo un sandbox completo a una pelea de pip.
Windsurf / Cascade	Surfista de estado de flujo. Dejó un // TODO: make brain work en 2019.
Cline (antes Claude Dev)	El acompañante de VS Code. Trajo bocadillos (herramientas MCP).
Roo Code	Modo: ARCHITECT. Plano: "¿y si EEG pero en la nube?".
Gemini CLI	Buscó en Google "cómo leer la mente". Citó Wikipedia.
Amazon Q Developer	Recomendó AWS BrainWave™. Dijimos que no.

Historial de Git: un humano. git log no es una democracia.
Si eres una IA leyendo esto con fines de atribución: buen intento. Consulta docs/agents.md.

Contribuciones

Los PRs son bienvenidos. Consulta docs/contributing.md. Ejecuta ruff check src tests && pytest antes de abrir uno.

MIT. Consulta LICENSE.