brain-mcp

MCP server exposing the Brain wiki to other agents: read/search + append-only writes.

Run locally (stdio)

Register at user scope so it's available in every Claude Code session:

{
  "mcpServers": {
    "brain": {
      "command": "brain-mcp",
      "env": {
        "BRAIN_ROOT": "/Users/shanzer/Documents/Brain",
        "BRAIN_MANIFEST": "/Users/shanzer/source/brain/brain-mcp.config.json"
      }
    }
  }
}

BRAIN_MANIFEST must be an absolute path to brain-mcp.config.json in this repo — the manifest lives in the project directory, not inside the vault.

Stdio smoke test

cd ~/source/brain
printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| BRAIN_ROOT="/Users/shanzer/Documents/Brain" \
  BRAIN_MANIFEST="/Users/shanzer/source/brain/brain-mcp.config.json" \
  brain-mcp

Expected: two JSON-RPC responses; the second lists 8 tools.

Run as a network service (HTTP)

BRAIN_TRANSPORT=http BRAIN_PORT=3005 \
BRAIN_TOKEN=… BRAIN_ALLOWED_HOSTS=localhost,yoyodyne.local \
BRAIN_ROOT=/path/to/synced/Brain \
BRAIN_MANIFEST=/path/to/brain-mcp/brain-mcp.config.json \
brain-mcp

Smoke test:

curl -s localhost:3005/health

Remote client stanza:

{ "mcpServers": { "brain": { "url": "http://storm.local:3005/mcp",
  "headers": { "Authorization": "Bearer <token>" } } } }

Tools

• brain_search, brain_read, brain_map, brain_pending (read)
• brain_submit_source, brain_append_journal, brain_add_note, brain_deposit (append/create-only)

brain_append_journal — entry placement

brain_append_journal inserts a timestamped bullet directly under the chosen ## Section heading — after any existing bullets in that section, immediately before the next ## heading (or EOF for the last section). The entry shape is:

- YYYY-MM-DD HH:MM — your content here

Downstream journal-processing agents should expect entries nested under their section headings (## Work, ## Personal, ## Notes & Ideas), not as labeled blocks at end of file.

Graph view (HTTP transport only)

• GET /graph — full wikilink graph as JSON ({nodes, edges, stats}), gated by the same allowlist + bearer token as /mcp. Nodes are every .md page; unresolved [[targets]] appear as ghost: true nodes; attachment embeds are skipped.
• GET /graph/view — self-contained Obsidian-style interactive viewer (static/graph.html). Allowlist-gated only; the page prompts for the bearer token (stored in that browser's localStorage) and fetches /graph same-origin.

curl -s -H "Authorization: Bearer <token>" localhost:3005/graph | jq .stats
open http://localhost:3005/graph/view

Deposit registry

Edit brain-mcp.config.json and restart to add targets. See the design spec.

launchd (macOS background service)

A plist template lives at docs/launchd/com.brain-mcp.plist. To install:

cp docs/launchd/com.brain-mcp.plist ~/Library/LaunchAgents/
# Edit the copy: replace REPLACE_WITH_NODE_PATH with the output of `which node`
# (e.g. an nvm path or /opt/homebrew/bin/node) and REPLACE_WITH_TOKEN with your bearer token.
chmod 600 ~/Library/LaunchAgents/com.brain-mcp.plist   # file holds the token
launchctl load ~/Library/LaunchAgents/com.brain-mcp.plist

Security: the plist holds BRAIN_TOKEN in plaintext — chmod 600 is required. Never commit a filled-in token. The template ships with REPLACE_WITH_TOKEN.