MCP server · second brain
A brain. Several AI clients.
Exposes the astra-2cerebro kit's Markdown folder as MCP tools for Claude Code, Codex, Claude Desktop, n8n, and bots. Read-only by default; writing only if you enable it.
Exposes the astra-2cerebro kit's Markdown folder as MCP tools for Claude Code, Codex, Claude Desktop, n8n, and bots. Read-only by default; writing only if you enable it.
The astra-2cerebro kit stores who you are, your priorities, decisions, projects, and a linked wiki in Markdown files. cerebro-mcp starts an MCP server pointed to that folder, and each client gets the tools cerebro_*. The brain remains just files; what changes is who can read them.
Context, priorities, route map, search, reading, wiki, projects, connections, and routines. Plus three writing tools (decision, source, execution) that only appear when you enable --escrita.
Every path goes through a check that blocks ../, absolute paths from outside, symlinks pointing outside, .git, node_modules e .env. Nothing leaves the machine.
Via stdio for Claude Code, Codex, and Claude Desktop. With --http, an endpoint at 127.0.0.1 for n8n, bots, and scripts. No index, no database: reads from disk on the fly.
The client starts the server as a child process, asks which tools are available, and calls them when needed. The server reads the folder on the spot and returns Markdown text with the file path so the model can cite the source.
--dir, then CEREBRO_DIR, then the current folder if it exists AGENTS.md or CLAUDE.md. Without a brain, a clear error and exit code 1.
Ten read tools and the resources cerebro:// always; the three write tools only with --escrita or CEREBRO_ESCRITA=1.
Each call reads from disk, builds Markdown, and returns it. A predictable error becomes isError; the process never crashes because of a bad call.
| Tool | What it does | Writing |
|---|---|---|
cerebro_contexto() | about-me + about-the-work + priorities, with the paths | no |
cerebro_prioridades() | only contexto/prioridades.md | no |
cerebro_rotas() | the “Route map” section of AGENTS.md / CLAUDE.md | no |
cerebro_buscar(consulta, limite?) | search for terms across all .md files, with excerpt and relevance | no |
cerebro_ler(caminho) | contents of a file or folder listing, only within the brain | no |
cerebro_wiki_indice() · cerebro_wiki_pagina(slug) | wiki index and page by slug | no |
cerebro_projetos() · cerebro_conexoes() · cerebro_rotinas() | projects with status, connections table, routines, and executions | no |
cerebro_registrar_decisao(...) | dated entry in decisoes/registro.md | yes |
cerebro_adicionar_fonte(nome, conteudo) | fontes/AAAA-MM-DD-slug.md, without overwriting | yes |
cerebro_registrar_execucao(id, resultado, ...) | new line in the routine execution log | yes |
No database, no external service. Just Node, a brain folder, and an MCP client.
The server is pure ESM. If you use Claude Code or Codex, you already have it.
# check the version node --version
A folder with AGENTS.md/CLAUDE.md, contexto/, wiki/, decisoes/. If you don’t have one yet, install the kit.
# the kit creates the structure git clone https://github.com/inematds/astra-2cerebro
Claude Code, Codex, Claude Desktop — or n8n/a bot in HTTP mode.
# example: Claude Code installed claude mcp list
All commands are real and in the repository. Replace /home/voce/meu-cerebro through your brain folder.
Downloads the server, installs the official SDK, and runs the 42 tests against the included fixture.
git clone https://github.com/inematds/cerebro-mcp.git cd cerebro-mcp npm install npm test # ℹ tests 42 · pass 42 · fail 0
The script starts the actual binary and communicates over JSON-RPC via stdio: initialize, tools/list, tools/call.
node scripts/teste-stdio.mjs /home/voce/meu-cerebro # OK initialize → cerebro-mcp server 1.0.0 (protocol 2025-06-18) # OK tools/list → 10 tools: cerebro_contexto, cerebro_prioridades, ... # OK tools/call cerebro_ler ../../etc/passwd → isError (Access denied)
One line. To let the agent record decisions and sources, add --escrita at the end.
claude mcp add cerebro -e CEREBRO_DIR=/home/voce/meu-cerebro -- node /home/voce/cerebro-mcp/bin/cerebro-mcp.mjs # or, versioned in the project: .mcp.json with {"mcpServers":{"cerebro":{"command":"node","args":[...],"env":{"CEREBRO_DIR":"..."}}}}
Codex reads ~/.codex/config.toml; Claude Desktop reads claude_desktop_config.json. INSTALAR.md has both complete examples.
# ~/.codex/config.toml [mcp_servers.cerebro] command = "node" args = ["/home/voce/cerebro-mcp/bin/cerebro-mcp.mjs"] [mcp_servers.cerebro.env] CEREBRO_DIR = "/home/voce/meu-cerebro"
The agent decides on its own when to call each tool. Start with what requires context.
# you: Quais são as minhas prioridades deste trimestre? # agent → cerebro_prioridades() → responds citing contexto/prioridades.md # you: Por que decidimos fazer o site em gerador estático? # agent → cerebro_buscar("static site") → cerebro_ler("decisoes/registro.md")
Runs on 127.0.0.1, without a session. Requires the header Accept: application/json, text/event-stream; tools/call works without initialize before.
CEREBRO_DIR=/home/voce/meu-cerebro node bin/cerebro-mcp.mjs --http 3333 curl -s http://127.0.0.1:3333/mcp -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"cerebro_prioridades","arguments":{}}}'
The same folder, two different clients. The agent calls the tools; you just ask.
You (in Codex): What did Company X ask for at the last meeting?
→ cerebro_wiki_pagina("empresa-x") → cerebro_ler("wiki/fontes/2026-09-01-reuniao-empresa-x.md")
Agent: Approved the phase 2 scope, with a deadline at the end of October, and agreed to decide who will validate the weekly reports (source: wiki/fontes/2026-09-01-reuniao-empresa-x.md).
You (in Claude Code, server with --escrita): Records that we’ll accept phase 2, with a deadline in October, because phase 1 was approved.
→ cerebro_registrar_decisao(titulo, decisao, porque)
Agent: Recorded in decisoes/registro.md with today’s date: "## 2026-09-07: Accept phase 2 of Projeto Alfa". Would you like me to note the alternatives considered?
Version 1.0.0 covers the kit's entire lifecycle. The next phases are about convenience, not foundations.