MCP

Connect AI agents like Claude Code, Codex, and Cursor to your GalaxyBrain workspace. Read, write, search, and monitor your pages, templates, and layout in real time.

Setup

Prerequisites

• Bun runtime installed
• GalaxyBrain open in a Chromium-based browser (Chrome or Edge)

Install

Ask your AI assistant to install the GalaxyBrain MCP server (galaxybrain-mcp).

Or install manually. Add to your tool's MCP settings:

{
  "mcpServers": {
    "galaxybrain": {
      "command": "npx",
      "args": ["-y", "galaxybrain-mcp"]
    }
  }
}

The MCP server starts a local API server automatically if one isn't already running. It communicates with GalaxyBrain browser tabs over a local WebSocket connection (default port 1924).

Port override

{
  "mcpServers": {
    "galaxybrain": {
      "command": "npx",
      "args": ["-y", "galaxybrain-mcp"],
      "env": { "GB_API_PORT": "3000" }
    }
  }
}

If you override the port, also pass ?gb_port=3000 in the GalaxyBrain browser URL.

How It Works

AI Tool (Claude Code, Cursor, etc.) ↕ MCP protocol (stdio)GalaxyBrain MCP Server↕ WebSocket (localhost:1924)GalaxyBrain API Server↕ WebSocketGalaxyBrain Browser Tab(s)

The MCP server is a thin translation layer. It receives tool calls from your AI assistant, converts them to WebSocket commands, sends them to the API server, and formats the responses.

Multiple MCP server processes can connect simultaneously. The API server is started automatically if not already running. When the MCP session that spawned the API server exits, it terminates the API server. Other connected MCP sessions will automatically re-spawn it on their next command.

Version Checking

The MCP server performs two version checks:

1. Protocol compatibility — Before connecting to an API server, the MCP server checks the API server's protocol version. If the versions don't match, it returns an error with instructions.
2. npm update check — On startup, the MCP server checks the npm registry for newer versions of galaxybrain-mcp. If an update is available, it logs a warning.

Tools Overview

The MCP server provides 13 tools. Use galaxybrain_help to look up detailed schemas for complex nested payloads.

galaxybrain_status

Check whether the API server is running and list connected browser tabs. Shows each tab's state, project, and connection details. Use this first to confirm connectivity.

galaxybrain_project

Manage the project lifecycle: list available folders, open folder by ID, open demo by name, close the current project.

galaxybrain_read_pages

Read full serialized content of pages or templates. Manage selection by ID or read all open tabs. Control returned fields with icon, title, subtitle, blocks flags.

galaxybrain_query

Search and filter pages with text search, error search, references search, graph filters, count filters, field projection, sorting, and pagination.

galaxybrain_traverse

Build a recursive page-link tree starting from a root page:

• down (MAP) — walks outbound links.
• up (ANCESTORS) — walks inbound links.

galaxybrain_write_pages

Create, update, or delete pages or templates. Supports full replacement, surgical block-level edits, and image uploads via base64.

galaxybrain_create_from_template

Create a page from a template with automatic value resolution. A page link is inserted into the specified source block.

galaxybrain_items

Push (insert) or pop (remove) items from specific blocks. Useful for appending tasks, inserting links, or removing items.

galaxybrain_workspace

Read or write the workspace tab layout. Supports optimistic concurrency via readVersion.

galaxybrain_watch

Start watching for real-time events. Returns a shell command to run with your AI tool's process monitor.

galaxybrain_update

Warm the npx cache for galaxybrain-mcp@latest. On success, returns a message instructing the user to restart their MCP host.

galaxybrain_help

Look up detailed documentation on a specific topic during a session. Available topics include overview of tools, styles, units, errors, and troubleshooting.

Typical Workflow

1. galaxybrain_status → check connectivity, see open instances
2. galaxybrain_orient → understand the project structure
3. galaxybrain_read_pages → read content
4. galaxybrain_query → search and filter
5. galaxybrain_traverse → explore link structure
6. galaxybrain_write_pages → create/update/delete pages
7. galaxybrain_items → insert/remove items
8. galaxybrain_create_from_template → create from template

If no project is open, use galaxybrain_project to list and open one first.

Data Model

GalaxyBrain organizes content in a hierarchy: Pages → Blocks → Items → Units.

Pages

Blocks

Items

Units

Templates

Templates are special pages that serve as blueprints. They use the same structure as regular pages but can contain templateValue units.

Writing Content

Creating a Page

Pass a full page body to galaxybrain_write_pages with action: "create":

{
  "action": "create",
  "pages": [{
    "icon": "📝",
    "title": [{ "type": "text", "text": "My Page" }],
    "blocks": [{
      "blockId": 0,
      "items": [{
        "type": "text",
        "content": [{ "type": "text", "text": "Hello world" }]
      }]
    }]
  }]
}

Updating a Page

For a full replacement, pass the complete page body with a pageId:

{
  "action": "update",
  "pages": [{
    "pageId": "AbcDef1234567890GhIj",
    "icon": "🔥",
    "title": [{ "type": "text", "text": "Updated Title" }],
    "blocks": [{ "blockId": 0, "items": [...] }]
  }]
}

Push and Pop

Use galaxybrain_items for targeted insertions and removals:

Push (insert items)

{
  "action": "push",
  "operations": [{
    "pageId": "AbcDef1234567890GhIj",
    "blockId": 0,
    "items": [{
      "type": "text",
      "content": [{ "type": "text", "text": "New task" }]
    }]
  }]
}

Pop (remove items)

{
  "action": "pop",
  "operations": [{
    "pageId": "AbcDef1234567890GhIj",
    "blockId": 0,
    "count": 1
  }]
}

Normalization

Written content is normalized automatically; adjacent compatible units are merged.

Output Modes

Versions & Conflict Detection

Each page has an independent integer version that increments on every mutation. Pass readVersion with mutations for optimistic concurrency.

Troubleshooting

Prerequisites

• GalaxyBrain MCP requires Bun.

Updating

The MCP server checks for updates on startup.

Common Errors