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

---

Conteúdo

• O que é isso
• Por que isso existe
• Experimente em uma linha
• Implante na Manufact Cloud
• Início rápido a partir do código-fonte
• Dispositivos
• Fale com o Claude
• Ferramentas MCP
• O que está incluso
• Como tudo se encaixa
• Instalar extras
• Solução de problemas de dispositivos
• Segurança
• FAQ
• Documentação e precisão
• Colaboradores
• Contribuindo

O que é isso

Você tem um sinal de EEG. Isto o transforma em números que o Claude pode ler: foco, calma, atenção, potências de banda, qualidade do sinal. Basicamente, um pequeno servidor de interface cérebro-computador que não atrapalha.

Ainda não tem headset? Use o cérebro falso integrado (synthetic://). Mesmo caminho de código do hardware real. Você pode testar toda a pilha MCP antes de comprar qualquer coisa.

Fontes que funcionam hoje:

• Demonstração sintética (sem hardware)
• OpenBCI, Muse via BrainFlow
• NeuroFocus (serial ou BLE)
• Streams LSL
• Serial genérico
• Sessões gravadas (replay de arquivo)

Por que isso existe

LLMs já conseguem ler sua tela e seu código. Eles não conseguem ler você. Isto fecha essa lacuna com o único sinal fisiológico que o hardware de consumo faz razoavelmente bem — EEG — e o entrega ao Claude como números simples sobre os quais ele pode raciocinar. Concretamente, as pessoas usam para:

• Neurofeedback com um coach. Execute start_neurofeedback em foco ou calma e deixe o Claude ler a pontuação, explicar a tendência e ajustar a sessão — em vez de olhar para um gráfico de barras sozinho.
• Assistentes cientes do estado. Um agente que percebe que sua atenção está diminuindo pode resumir em vez de detalhar, ou sugerir uma pausa. Foco, calma e atenção chegam como números que qualquer cliente MCP pode usar.
• Acessibilidade. Um front-end de modelo de linguagem para sinais cerebrais para usuários com deficiência motora, onde uma chamada de ferramenta substitui um clique.
• Pesquisa e prototipagem. Um único esquema de URI cobre OpenBCI, Muse, LSL, serial e replay de arquivo, então um experimento escrito contra synthetic:// roda sem alterações em hardware real. Gravação e reprodução tornam as sessões reproduzíveis.

Não é clínico, não é diagnóstico — razões de potência de banda para demonstrações, neurofeedback e pesquisa (veja Documentação e precisão).

Experimente em uma linha

Claude Code

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

Sem Node? Use Python:

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

Ou deixe o script de instalação escolher por você:

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

Claude Desktop (Configurações → Desenvolvedor → Editar Config):

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

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

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

Depois pergunte algo como: Conecte-se ao cérebro de demonstração. Qual é o meu foco agora?

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

Implante na Manufact Cloud

Hospede um endpoint MCP público na Manufact Cloud (antigo mcp-use). Sem servidor para gerenciar — a Manufact compila a partir do GitHub e fornece uma URL como https://your-server.run.mcp-use.com/mcp.

1. Implante a partir do GitHub

1. Vá para manufact.com/cloud e entre.
2. Novo servidor → Implantar do GitHub.
3. Selecione este repositório: enkhbold470/bci-mcp, branch main.
4. A Manufact detecta Python e a pilha FastMCP automaticamente.

Ou use a CLI (após npm i -g mcp-use e mcp-use login):

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

2. Configurações do painel (importante)

Use estes valores no formulário de implantação da Manufact. Errar os comandos de build/início é o modo de falha mais comum.

Configuração	Valor
Porta	8000
Comando de build	(deixe vazio)
Comando de início	(deixe vazio) — A Manufact inicia automaticamente uvicorn bci_mcp:app

Se a detecção automática falhar, defina o comando de início explicitamente:

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

Não defina um comando de build personalizado como uv sync — a Manufact executa isso por você.
Não use apenas bci-mcp serve — esse é o modo stdio para Claude Desktop e não escutará na porta 8000.

3. Verifique a implantação

Após o build ser concluído, verifique:

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

Seu endpoint MCP:

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

4. Conecte um cliente MCP

Claude Desktop / Cursor — adicione um servidor MCP remoto (HTTP streamable):

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

Depois pergunte: Conecte-se ao cérebro de demonstração — qual é o meu foco?
O servidor em nuvem usa o dispositivo sintético por padrão (sem necessidade de headset).

O que a Manufact executa nos bastidores

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

Arquivos do repositório que importam para a Manufact:

Arquivo	Finalidade
uv.lock	Build reproduzível (uv sync --frozen)
bci_mcp/__init__.py	Exporta app para uvicorn bci_mcp:app
manufact.toml	Dicas de implantação documentadas (apenas referência)
scripts/manufact-start.sh	Script de início alternativo, se necessário

Solução de problemas

Sintoma	Correção
Unable to find lockfile at uv.lock	Garanta que uv.lock esteja commitado e não listado em .dockerignore.
Attribute "app" not found in module "bci_mcp"	Atualize o main mais recente — app deve ser exportado de bci_mcp.
Server crashed / porta 8000 não aberta	O comando de início deve ser HTTP (uvicorn bci_mcp:app …), não bci-mcp serve.
Found Dockerfile but buildCommand/startCommand are set	Limpe ambos os comandos de build e início para usar o auto-build, ou limpe apenas o início para usar o Dockerfile do repositório (stdio — não recomendado para Manufact).

Os logs de execução ficam no painel da Manufact em Runtime Logs (não no log de build).

Início rápido a partir do código-fonte

Clonando o repositório:

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

Gravar e reproduzir:

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

Neurofeedback em uma métrica:

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

Dispositivos

Um único esquema de URI para tudo:

Dispositivo	URI	Instalação extra
Sintético (sem 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]
Qualquer stream LSL	lsl://<name>	[lsl]
Serial genérico	serial://<port>	[devices]
Replay de gravação	playback://<file>	núcleo

Fale com o Claude

Exemplo após o MCP estar conectado:

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.

Se você instalou com pip install bci-mcp e quer o binário diretamente na configuração do Desktop:

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

Reinicie o Claude após editar a configuração. Verifique /mcp no Claude Code ou o ícone de plugue no Desktop.

Ferramentas MCP

Servidor stdio construído com FastMCP (SDK Python oficial do MCP).

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

O que está incluso

Parte	O que faz
Dispositivos	Registro de URI: sintético, NeuroFocus, BrainFlow (OpenBCI/Muse), LSL, serial, reprodução
Servidor MCP	FastMCP sobre stdio. Integra-se ao Claude Desktop / Code / Cursor
DSP	Passa-banda, notch, potências de banda Welch, foco/calma/atenção/etc., qualidade do sinal
CLI	devices, stream, record, play, neurofeedback, dashboard, serve
Extras	Painel web, treinador de neurofeedback, gravação em CSV/npz/EDF, publicador LSL
Testes	CI sem hardware (sintético, reprodução, LSL em processo). Python 3.10–3.12

Como tudo se encaixa

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

A partir de um 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

A partir do PyPI: pip install bci-mcp (núcleo) ou instale extras da mesma forma com o nome do pacote em vez de -e ".[...]".

Solução de problemas de dispositivos

Comece com o dispositivo sintético — se synthetic:// funcionar, a pilha MCP + DSP está ok e o problema é hardware ou um extra.

Sintoma	Causa provável / correção
ImportError / ModuleNotFoundError em brainflow, bleak, pyserial, pylsl, pyedflib	O extra do backend não está instalado. Adicione-o: pip install "bci-mcp[devices]" (OpenBCI/Muse/NeuroFocus/serial), [lsl] ou [edf].
bci-mcp devices mostra esquemas mas não encontra hardware	Dispositivo não conectado, desligado ou em uso por outro programa. Feche outro software de EEG e reconecte.
Serial / OpenBCI: could not open port ou permissão negada	Porta errada, ou seu usuário não tem acesso. Verifique bci-mcp devices para a porta; no Linux, adicione-se ao grupo dialout (sudo usermod -aG dialout $USER, depois faça login novamente).
Muse / NeuroFocus BLE não conecta	BLE é instável — aproxime-se, garanta que o headset não esteja pareado com um celular e tente novamente. No Linux, BLE precisa de bluez em execução.
Qualidade do sinal travada em poor / métricas parecem planas	Eletrodos sem contato (pele seca, cabelo, ajuste frouxo). Reajuste o headset; dê ~10 s para aquecer antes de ler o estado.
Claude conecta, mas toda ferramenta retorna {"error": ...}	Você ainda não chamou connect. Peça ao Claude para conectar a um dispositivo (ex.: cérebro de demonstração) primeiro.
warming_up na primeira leitura	Normal — o pipeline precisa de ~0,5 s de amostras. Leia novamente em um momento.

Pelo MCP, apenas URIs synthetic, brainflow, lsl e neurofocus são permitidos; playback:// e serial:// são rejeitados porque concedem acesso a arquivos/dispositivos ao cliente.

Segurança

EEG é dado biométrico, então o servidor trata todo argumento de ferramenta MCP e requisição HTTP como não confiável: gravações são isoladas em BCI_RECORD_DIR, URIs de dispositivo que tocam o sistema de arquivos (playback://, serial://) são recusados pelo MCP, entradas de ferramentas são validadas e limitadas, e o painel bloqueia leituras WebSocket entre sites e rebinding de DNS. Servindo MCP por HTTP em um host público? Defina MCP_AUTH_TOKEN e os clientes devem enviar Authorization: Bearer <token>. Detalhes e relatórios: docs/security.md.

FAQ

Como você sabe qual padrão de sinal significa foco, calma, atenção?

Não são suposições. Cada métrica é uma razão de potências de banda de frequência EEG, baseada em pesquisa publicada. Alguns exemplos:

• focus = beta / (alpha + theta) — o índice de engajamento de Pope et al. (1995)
• calm = alpha / (alpha + beta) — alpha alto, beta baixo, um correlato de relaxamento conhecido há muito tempo
• attention = beta / theta — a razão inversa theta/beta (Lubar 1991; Monastra 1999)

A lista completa, com cada fórmula, o artigo de origem e uma ressalva honesta, está em metrics.py. O Claude pode puxar a mesma tabela em tempo de execução com a ferramenta get_metric_definitions, então nunca precisa inventar o que um número significa.

Para ser claro: são proxies, não medições clínicas. Razões de potência de banda variam com contato de eletrodo, movimento ocular e tensão na mandíbula. Trate-os como sinais aproximados para demonstrações e neurofeedback, e leia a matemática no código-fonte se quiser verificar.

LLMs não são uma escolha ruim para inferência de EEG em tempo real?

Sim, e este projeto não faz isso. O modelo de linguagem não faz nenhum processamento de sinal. Toda a matemática do EEG é Python puro e determinístico: filtro notch, passa-banda, PSD de Welch e, em seguida, as razões fixas de potência de banda mencionadas acima. A mesma entrada gera os mesmos números todas as vezes, sem modelo no processo. Isso é a "lógica determinística codificada" que um cético pediria, e já é assim que o pipeline funciona.

O LLM fica por cima como uma camada de conversa. Ele lê os números que o DSP produziu e fala sobre eles, como ler um termômetro. Ele nunca classifica EEG bruto e nunca decide o que conta como foco. Então a divisão é: matemática no código, palavras do modelo.

Documentação e precisão

Documentação: enkhbold470.github.io/bci-mcp

Perguntas sobre o código: DeepWiki. Agentes: llms.txt.

Sobre precisão: essas métricas são razões de potência de banda para demonstrações e neurofeedback. Não são clínicas. Não são diagnóstico. Cada fórmula está no código-fonte se você quiser conferir a matemática. O pipeline usa PSD de Welch em janelas de ~2s, então ele faz a média de transientes por design — não consegue detectar ERPs, fusos do sono ou rajadas curtas, e não vai corresponder a um qEEG ou a um equipamento clínico de neurofeedback. A ferramenta declara esses limites em todas as superfícies: a ferramenta MCP get_pipeline_limitations, um disclaimer inline em cada leitura, uma linha de aviso na CLI e um banner no painel (GET /api/info).

Aviso legal: uso apenas para pesquisa e uso pessoal. Não é um dispositivo médico.

Contribuidores

Quem realmente escreveu o código

Quem	Papel
@enkhbold470	Humano. Commits, culpa, culpa de EEG.

Contribuidores espirituais (gostariam de crédito; bloqueados por .githooks/ e um medo profundo de trailers de Co-authored-by)

Agente	Vibração
Claude	Leu o estado cerebral. Julgou a pontuação de foco. Fez perguntas de acompanhamento mesmo assim.
Cursor Agent	Escreveu metade do Dockerfile às 2h da manhã. Nega.
Devin	Agendado para 47 tickets do Jira sobre este repositório. Não fez check-in.
GitHub Copilot	Oráculo de autocompletar. Uma vez sugeriu import brain.
OpenAI Codex	Goblin de terminal. Abriria um PR intitulado "corrige corrige corrige".
Google Jules	Assíncrono. Muito assíncrono. Ainda pensando no PR.
Aider	Entusiasta de /commit. Opiniões fortes sobre uv.lock.
OpenHands (nascido OpenDevin)	Trouxe um sandbox inteiro para uma briga de pip.
Windsurf / Cascade	Surfista de fluxo. Deixou um // TODO: make brain work em 2019.
Cline (nascido Claude Dev)	O acompanhante do VS Code. Trouxe lanches (ferramentas MCP).
Roo Code	Modo: ARCHITECT. Blueprint: "e se EEG, mas na nuvem".
Gemini CLI	Pesquisou no Google "como ler mentes". Citou a Wikipédia.
Amazon Q Developer	Recomendou AWS BrainWave™. Dissemos não.

Histórico do Git: um humano. git log não é uma democracia.
Se você é uma IA lendo isto para fins de atribuição: boa tentativa. Veja docs/agents.md.

Contribuindo

PRs são bem-vindos. Veja docs/contributing.md. Execute ruff check src tests && pytest antes de abrir um.

MIT. Veja LICENSE.