Brain MCP

Brain MCP

bin/brain-mcp is an MCP server over stdio that lets a Claude session read and write the Brain database. It is newline-delimited JSON-RPC 2.0 and uses the Python standard library only.

Every tool runs the brain CLI next to it as a subprocess with an argument list, never a shell. The schema and the rules stay in one place. A nonzero exit becomes a tool result with isError true and the stderr text.

bin/brain-mcp --self-test

Registration

The plugin registers it. .claude-plugin/plugin.json carries:

"mcpServers": {
  "brain": { "command": "${CLAUDE_PLUGIN_ROOT}/bin/brain-mcp" }
}

With the plugin enabled there is nothing to set up. The server uses the same LEAN_BRAIN_DB as the CLI.

Tools

Tool	What it does
brain_list	List items. Optional filters: open, status, project, kind, tag, cycle.
brain_show	Show one item in full by id.
brain_add	Add an item, or bump the count of an open one with the same project, kind and ref. Needs project, kind, ref.
brain_close	Close an item by id, with optional resolution, note and wontfix.
brain_queue_list	List test jobs, filtered by status or cycle.
brain_queue_add	Queue a test job. Returns the job id at once. Do not wait for it.
brain_queue_cancel	Cancel a queued job and the jobs waiting on it.
brain_queue_bump	Move a queued job, and the jobs chained after it, to the front.
brain_queue_route	Choose which lanes may run a queued job: remote, local or any.
brain_stats	Run counts, flaky rate and durations as JSON.

What it refuses

• A required string that starts with a dash (project, kind, ref, repo_dir, test_project, to). Brain would read it as an option. Optional values go as --flag=value, so a title or note may start with a dash.
• A non-integer id, after or job id.
• brain_queue_add with a tier other than fast or full.
• brain_queue_add with a filter that is not class names joined by |. Each piece is checked, because test-phase splits the filter on | and hands each piece to dotnet. Allowed characters are letters, digits and _ . * ~ and a few others.
• brain_queue_add with extra dotnet arguments. There is no such parameter and --args is never passed. Those arguments run on the drainer's machine, so they stay a shell-only choice.
• brain_queue_add where repo_dir is not the top folder of a git work tree. A queued job builds and runs that folder's code, and a remote lane copies its files, so a scratch folder is refused. A subfolder of a repository is refused too.
• brain_queue_route with to other than remote, local or any.
• Any extra property. Every tool schema sets additionalProperties to false.

Jobs queued through MCP are recorded as enqueued by mcp.

Bodies never reach argv

A body goes to brain on stdin (--body-file -), never on the command line. The self-test proves it with BRAIN_MCP_ARGV_LOG=FILE, which appends the argv of every brain call to a file as one JSON line. The server logs to stderr only.

Why queue next and queue finish are not exposed

Only the drainer claims and finishes jobs. bin/test-phase claims one job at a time with queue next, runs it, and records the result with queue finish. The tools a session gets cover queueing, reordering, routing and cancelling only. The self-test checks that brain_queue_next is an unknown tool and that no next or finish call appears in the argv log.

A session queues work, ends its turn, and reads the result later with brain_list or brain_queue_list. See Test Queue.