Brain Operator

A TypeScript MCP server that lets ChatGPT and other MCP clients read and safely modify TheBrain through the TheBrain REST API.

Setup

npm install
cp .env.example .env
# edit .env and set THEBRAIN_API_KEY
npm run dev

The server defaults to:

• GET /health
• POST /mcp
• GET /brain/health
• POST /brain/mcp
• GET /brain/v012/health
• POST /brain/v012/mcp
• TheBrain Cloud API base URL: https://api.bra.in
• TheBrain Local API base URL: http://localhost:8001/api

Set THEBRAIN_MODE=local when you want the normal brain, thought, note, link, and attachment tools to use TheBrain desktop Local API instead of TheBrain Cloud API. In local mode those tools authenticate with THEBRAIN_LOCAL_API_TOKEN and use THEBRAIN_LOCAL_BASE_URL; THEBRAIN_API_KEY is only required in cloud mode.

Health

curl http://localhost:3000/health

Expected:

{
  "ok": true,
  "name": "brain-operator-mcp",
  "version": "0.1.5"
}

MCP Inspector

npm run inspect

Use http://localhost:3000/mcp as the Streamable HTTP endpoint.

ChatGPT App Endpoint

For development, expose the local server through HTTPS:

npm run dev
ngrok http 3000

Then add this MCP server endpoint in ChatGPT developer mode:

https://<ngrok-subdomain>.ngrok.app/mcp

If MCP_API_TOKEN is set, clients must send:

Authorization: Bearer <MCP_API_TOKEN>

Shared Domain Path Routing

If mcp.gamescrazy.win is already used by another MCP service, keep that service on /mcp and expose this server under /brain/mcp.

Cloudflared ingress example:

ingress:
  - hostname: mcp.gamescrazy.win
    path: /brain/.*
    service: http://127.0.0.1:3000
  - hostname: mcp.gamescrazy.win
    service: http://127.0.0.1:7676
  - service: http_status:404

Then use this MCP endpoint:

https://mcp.gamescrazy.win/brain/mcp

Tools

Read-only:

• health_check
• list_brains
• get_brain
• search_thoughts
• get_thought
• get_thought_graph
• get_note
• list_attachments

Safe writes:

• create_thought
• update_thought
• create_link
• append_note
• replace_note
• add_url_attachment

Local app control:

• get_app_state
• open_brain
• activate_thought
• close_brain_tab

Plan workflow:

• create_change_plan
• create_note_update_plan
• get_change_plan
• discard_change_plan
• commit_change_plan

Batch plans support create_thought, create_link, append_note, and replace_note changes. Use create_note_update_plan when a client hides or blocks the direct replace_note tool; it creates a pending plan for a full note update and still requires commit_change_plan with confirm: true before TheBrain is changed.

Local App Control

The MCP server can control the local TheBrain desktop client through TheBrain Local API.

1. In TheBrain desktop, enable Local API in settings.
2. Copy the Local API token into THEBRAIN_LOCAL_API_TOKEN in .env.
3. Set THEBRAIN_LOCAL_BASE_URL if your Local API is not on http://localhost:8001/api.

Local-only tools:

• get_app_state
• open_brain
• activate_thought
• close_brain_tab

open_brain, activate_thought, and close_brain_tab require WRITE_TOOLS_ENABLED=true because they change local client UI state.

Safety

• Never put a real API key in source, docs, tests, logs, screenshots, or commits.
• Single-step write tools respect WRITE_TOOLS_ENABLED.
• Destructive tools are not registered in v0.1.
• Batch writes must be created as a plan, reviewed by the user, then committed by planId.
• Notes are append-only and limited by MAX_NOTE_CHARS.
• replace_note is the explicit full-note content setting tool. It sends the provided Markdown body to TheBrain's note update endpoint and is kept separate from append_note.
• URL attachments reject local and private-network hosts.

Manual Smoke Tests

Read-only:

Call list_brains.
Pick a brainId.
Call search_thoughts with queryText = "test".
Call get_thought on one result.

Single-step write:

Call create_thought:
- name: "[MCP_TEST] Brain Operator Smoke Test"
- label: "Created by brain-operator-mcp smoke test"

Call append_note on created thought:
- markdown: "This is a smoke test note."

Batch plan/commit:

The example below uses redacted placeholders. Do not paste private source notes into public docs, issues, or screenshots.

{
  "title": "[MCP_TEST] Redacted Import",
  "changes": [
    {
      "id": "c1",
      "op": "create_thought",
      "clientRef": "t_root",
      "name": "[MCP_TEST] REDACTED_ROOT_TOPIC",
      "label": "[REDACTED_LABEL]"
    },
    {
      "id": "c2",
      "op": "create_thought",
      "clientRef": "t_core_loop",
      "name": "[MCP_TEST] REDACTED_CHILD_TOPIC"
    },
    {
      "id": "c3",
      "op": "create_link",
      "fromRef": "t_root",
      "toRef": "t_core_loop",
      "relation": "child"
    },
    {
      "id": "c4",
      "op": "append_note",
      "targetRef": "t_root",
      "markdown": "[REDACTED_MARKDOWN_CONTENT]"
    },
    {
      "id": "c5",
      "op": "replace_note",
      "targetRef": "t_core_loop",
      "markdown": "[REDACTED_REPLACEMENT_MARKDOWN]"
    }
  ]
}

Then call commit_change_plan with:

{
  "planId": "returned_plan_id",
  "confirm": true
}

Single-note update plan:

{
  "brainId": "brain_id",
  "thoughtId": "thought_id",
  "title": "Update note",
  "markdown": "[REDACTED_REPLACEMENT_MARKDOWN]"
}

Then call commit_change_plan with the returned planId and confirm: true.

Common Errors

• BRAIN_ID_REQUIRED: pass brainId or set THEBRAIN_DEFAULT_BRAIN_ID.
• WRITE_DISABLED: set WRITE_TOOLS_ENABLED=true when you intentionally want writes.
• UNSAFE_URL: use a public http or https URL.
• PLAN_NOT_PENDING: the plan was already committed, discarded, or expired.
• LOCAL_APP_TOKEN_REQUIRED: set THEBRAIN_LOCAL_API_TOKEN from TheBrain desktop Local API settings.
• LOCAL_APP_UNAVAILABLE: enable TheBrain Local API and check THEBRAIN_LOCAL_BASE_URL.
• LOCAL_APP_AUTH_FAILED: use the Local API token from TheBrain desktop settings.
• LOCAL_APP_ACTION_FAILED: check the brain/thought IDs and local client state.

Verification

npm run typecheck
npm run lint
npm test
npm run build