cerebro-mcp

🇧🇷 Português · 🇺🇸 English · 🇪🇸 Español

Servidor MCP (Model Context Protocol) que expõe o seu segundo cérebro — a pasta de Markdown criada pelo kit astra-2cerebro — como ferramentas para qualquer cliente MCP: Claude Code, Codex, Claude Desktop, n8n, bots e scripts.

Um cérebro. Vários clientes. Nenhuma cópia.

📖 Guia de uso

Guia completo (landing + passo a passo): https://inematds.github.io/cerebro-mcp/guia/

                     ┌──────────────┐
  Claude Code ──┐    │              │
  Codex ────────┼──► │  cerebro-mcp │ ──► ~/meu-cerebro/  (AGENTS.md, contexto/, wiki/, decisoes/ ...)
  Claude Desktop┤    │   (stdio ou  │
  n8n / bot ────┘    │    HTTP)     │
                     └──────────────┘

Related MCP server: obsidian-mcp

Por quê

O kit astra-2cerebro guarda quem você é, o que faz, suas prioridades, decisões, projetos e uma wiki interligada — tudo em arquivos Markdown. Isso funciona muito bem para o agente que abre a pasta. Mas o Codex no terminal, o Claude Desktop no notebook, um fluxo no n8n e um bot no celular não abrem a pasta.

O cerebro-mcp resolve isso: sobe um servidor MCP apontado para a pasta e cada cliente passa a ter cerebro_contexto, cerebro_buscar, cerebro_ler, cerebro_registrar_decisao e as demais ferramentas. O cérebro continua sendo só arquivos; quem muda é quem consegue lê-los.

Instalação em 1 minuto

Precisa de Node.js 20 ou superior.

git clone https://github.com/inematds/cerebro-mcp.git
cd cerebro-mcp
npm install
npm test                      # 42 testes contra a fixture em test/fixture

# aponte para o seu cérebro e teste por stdio
CEREBRO_DIR=~/meu-cerebro node scripts/teste-stdio.mjs ~/meu-cerebro

Registrar no Claude Code (uma linha):

claude mcp add cerebro -e CEREBRO_DIR=/caminho/do/cerebro -- node /caminho/cerebro-mcp/bin/cerebro-mcp.mjs

Codex, Claude Desktop, .mcp.json do projeto e modo HTTP: veja INSTALAR.md.

Como funciona

cerebro-mcp [--dir <pasta>] [--escrita] [--http <porta>] [--host <ip>]

Sem --http o servidor fala MCP por stdio — é o que Claude Code, Codex e Claude Desktop usam. Com --http ele sobe um endpoint Streamable HTTP (POST /mcp, sem sessão) para n8n, bots e scripts na mesma máquina.

Ferramentas

As três de escrita só aparecem quando o servidor sobe com --escrita. Detalhes, parâmetros e exemplos de retorno: docs/ferramentas.md.

Além das ferramentas, cada .md é exposto como recurso cerebro://<caminho> (por exemplo cerebro://wiki/entidades/empresa-x.md), para clientes que preferem "anexar" uma nota.

Exemplos de conversa

Com o servidor registrado, o agente decide sozinho quando chamar cada ferramenta.

Você: Quais são as minhas prioridades deste trimestre? Agente: (chama cerebro_prioridades) Três, segundo contexto/prioridades.md: entregar a fase 2 do Projeto Alfa até o fim de outubro, lançar o site novo e reduzir o relatório semanal de 4 horas para 1.

Você: Por que decidimos fazer o site em gerador estático? Agente: (chama cerebro_buscar("site estático"), depois cerebro_ler("decisoes/registro.md")) Em 2026-08-20 você registrou: custo zero e pouca manutenção; mudaria de ideia se precisasse de área logada.

Você: Registra que vamos aceitar a fase 2 com prazo em outubro. Agente: (servidor com --escrita; chama cerebro_registrar_decisao) Registrado em decisoes/registro.md com a data de hoje. Quer que eu anote as alternativas consideradas?

Você: O que a Empresa X pediu na última reunião? Agente: (chama cerebro_wiki_pagina("empresa-x"), segue os links para a fonte) Aprovou o escopo da fase 2 e ficou de definir quem valida os relatórios semanais.

Segurança

• Leitura por padrão. Sem --escrita, as ferramentas de escrita nem são registradas — o cliente não as vê. E mesmo com elas registradas, o núcleo confere a flag de novo antes de gravar.

• Só dentro da pasta. Todo caminho passa por caminhoSeguro: resolve, confere o prefixo, segue symlinks e confere de novo. ../, caminhos absolutos de fora e links apontando para fora são recusados.

• .env, .git e node_modules são invisíveis, mesmo para leitura.

• HTTP só em 127.0.0.1 por padrão, sem autenticação. Se expor em outra interface, coloque um proxy com autenticação na frente — e lembre que um cérebro contém dados pessoais.

• Nada sai da máquina. O servidor não faz requisições externas.

Detalhes em docs/seguranca.md.

Testes

npm test            # node --test: núcleo, escrita e servidor (cliente MCP em memória)
npm run teste:stdio # sobe o binário de verdade e conversa em JSON-RPC por stdio
npm run teste:http  # sobe --http em porta livre e faz as chamadas que um n8n faria

Resultado real da fumaça por stdio (node scripts/teste-stdio.mjs, contra test/fixture):

[servidor] [cerebro-mcp] pronto por stdio — cérebro em .../test/fixture (escrita desligada)
OK  initialize → servidor cerebro-mcp 1.0.0 (protocolo 2025-06-18)
OK  tools/list → 10 ferramentas: cerebro_contexto, cerebro_prioridades, cerebro_rotas, cerebro_buscar, cerebro_ler, cerebro_projetos, cerebro_conexoes, cerebro_rotinas, cerebro_wiki_indice, cerebro_wiki_pagina
OK  tools/call cerebro_buscar → 2 resultado(s) para "empresa x":
OK  tools/call cerebro_rotas → seção encontrada
OK  tools/call cerebro_ler ../../etc/passwd → isError (Erro: Acesso negado: "../../etc/passwd" está fora do cérebro.)
OK  resources/list → 27 recursos cerebro://

Com --escrita, o tools/list devolve 13 ferramentas (as 10 acima mais cerebro_registrar_decisao, cerebro_adicionar_fonte e cerebro_registrar_execucao). O npm test cobre: busca (relevância, acentos, wikilinks, pastas ignoradas), leitura com bloqueio de traversal/symlink/.env, extração de rotas e prioridades, projetos, conexões, rotinas, wiki, recursos, escrita bloqueada sem --escrita e funcionando com ela (em cópia temporária da fixture).

Documentação

• INSTALAR.md — Claude Code, Codex, Claude Desktop, .mcp.json, HTTP, e instruções para um agente instalar sozinho.

• docs/arquitetura.md — como o código está organizado.

• docs/ferramentas.md — cada ferramenta com parâmetros, retorno e exemplo.

• docs/seguranca.md — o que é bloqueado e por quê.

• docs/exemplos.md — n8n, bot e site chamando o servidor em modo HTTP.

• docs/faq.md — perguntas frequentes.

FAQ curta

Preciso do kit astra-2cerebro? O servidor lê a estrutura que o kit cria. Qualquer pasta com AGENTS.md ou CLAUDE.md sobe, mas as ferramentas de contexto, wiki e rotinas esperam os arquivos do kit.

Posso apontar dois clientes para o mesmo cérebro? Sim. Cada cliente sobe o próprio processo do servidor; todos leem a mesma pasta. Escrita simultânea é rara e as três operações só acrescentam texto.

O servidor indexa em algum lugar? Não. A busca varre os .md a cada chamada. Para cérebros com centenas de notas é instantâneo; para milhares ainda é aceitável.

Funciona no Windows? Sim, com Node 20+. Nos exemplos, troque os caminhos.

Mais em docs/faq.md.

Créditos e licença

Construído para o kit astra-2cerebro — a estrutura de pastas, o formato das decisões, rotinas, conexões e wiki vêm de lá. Usa o SDK oficial @modelcontextprotocol/sdk.

MIT — Copyright (c) 2026 inematds.