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 é isto
• Por que isto 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 vem no pacote
• Como tudo se encaixa
• Instalar extras
• Solução de problemas de dispositivos
• Segurança
• FAQ
• Documentação e precisão
• Colaboradores
• Contribuindo

O que é isto

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 um fone de cabeça? 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)
• Fluxos LSL
• Serial genérico
• Sessões gravadas (reprodução de arquivo)

Por que isto existe

LLMs já conseguem ler sua tela e seu código. Elas 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 assistir a um gráfico de barras sozinho.
• Assistentes cientes do estado. Um agente que percebe que sua atenção está caindo 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. Uma interface 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 reprodução 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 (anteriormente 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 uvicorn bci_mcp:app automaticamente

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 bci-mcp serve sozinho — 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 transmitível):

{
  "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 na nuvem usa o dispositivo sintético por padrão (sem fone de cabeça necessário).

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 a 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 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 fluxo LSL	lsl://<name>	[lsl]
Serial genérico	serial://<port>	[devices]
Reprodução 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 (14): list_devices, connect, disconnect, get_brain_state, get_band_powers, get_signal_quality, get_metric_definitions, get_pipeline_limitations, calibrate, record, start_neurofeedback, get_neurofeedback_score, mark_event, stream_summary

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

Prompt: interpret_brain_state

O que vem no pacote

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.14

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: 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 usado 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 fone não esteja pareado a 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 fone; 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 (por exemplo, o 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 sistema de arquivos/dispositivo 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, tirada de 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 onde vem 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. As fontes de cada métrica vêm com DOIs, e o recurso brain://citations as retorna como JSON, junto com a citação e licença do próprio software. Fontes que contestam uma métrica são marcadas como caveat para que um agente não possa citá-las como suporte. Para ser claro: estes são proxies, não medições clínicas. As razões de potência de banda variam com o contato dos eletrodos, 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 verificá-la.

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 de EEG é Python simples e determinístico: filtro notch, passa-banda, PSD de Welch, e então as razões fixas de potência de banda acima. A mesma entrada gera os mesmos números toda vez, sem modelo no loop. Essa é 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

Docs: enkhbold470.github.io/bci-mcp

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

Sobre precisão: estas 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 quiser verificar a matemática. O pipeline usa PSD de Welch em janelas de ~2s, então ele faz a média dos transientes por design — não consegue detectar ERPs, fusos ou rajadas curtas, e não vai corresponder a um qEEG ou 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: apenas para pesquisa e uso pessoal. Não é um dispositivo médico.

Contribuidores

Quem	Papel
@enkhbold470 (Enkhbold Ganbold)	Autor e mantenedor: design, integração de hardware NeuroFocus, revisão, lançamentos

Como ferramentas de codificação com IA foram usadas. Grande parte da reescrita de junho de 2026 foi escrita com assistentes de codificação com IA (Claude Code, Cursor) trabalhando a partir de especificações de design e planos mantidos em docs/superpowers/. O mantenedor dirigiu esse trabalho, revisou e testou as mudanças, e é responsável pelo código. O hook do repositório em .githooks/ remove trailers de Co-authored-by de IA, então git log não mostra quais commits tiveram ajuda de IA; este parágrafo é a divulgação.

Contribuindo

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

MIT. Veja LICENSE.