MCP

Setup

Prerequisites

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

Install

Ask your AI assistant to install the GalaxyBrain MCP server (package: galaxybrain-mcp). Most AI tools can configure MCP servers automatically.

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

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 (from the HTTP health check response "GalaxyBrain API Server/{version}"). If the versions don't match, it returns an error with instructions to stop the old server. This also applies after spawning a new API server, as a belt-and-suspenders check for npm dependency mismatches.
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 to stderr and prepends the update notice to galaxybrain_status, galaxybrain_orient, and galaxybrain_help responses. The raw galaxybrain_status output also exposes a structured mcp.updateState field so agents can detect the update programmatically and call galaxybrain_update to warm the npx cache.

Tools Overview

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

Typical Workflow

If no project is open, use galaxybrain_project to list and open one first. Most of the time, a project is already open in the browser.

Data Model

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

Pages

Read-only fields: blockOrder, createdAt, updatedAt, templateValues, counts.

Blocks

Items

Text item styles

Text items also support indentLevel (0-8) for nesting.

Units

Templates

Templates are special pages that serve as blueprints. They use the same structure as regular pages but can contain templateValue units resolved at creation time. Access templates by passing scope: "templates" to read, write, and items tools.

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" }],
    "subtitle": [],
    "blocks": [{
      "blockId": 0,
      "items": [{
        "type": "text",
        "style": "",
        "content": [{ "type": "text", "text": "Hello world" }]
      }]
    }]
  }]
}

Pass null in the pages array to create a default blank page.

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" }],
    "subtitle": [],
    "blocks": [{ "blockId": 0, "items": [...] }]
  }]
}

Surgical Updates

Modify specific blocks without replacing the entire page:

{
  "action": "update",
  "pages": [{
    "pageId": "AbcDef1234567890GhIj",
    "title": [{ "type": "text", "text": "New Title" }],
    "updateBlocks": [{ "blockId": 0, "items": [...] }],
    "insertBlocks": [{ "blockId": 5, "items": [...] }],
    "deleteBlockIds": [2, 3]
  }]
}

blocks (full replacement) and surgical fields are mutually exclusive.

Push and Pop

Use galaxybrain_items for targeted insertions and removals:

Push (insert items)

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

Pop (remove items)

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

Position reference

Batch Semantics

Create, update, delete, push, and pop all accept arrays. Each entry succeeds or fails independently. Responses include a results array aligned to input order.

Normalization

Written content is normalized automatically: adjacent compatible units are merged, lone pageLink units in unstyled text items are promoted to standalone items. Content may look different on read.

Output Modes

Defaults by tool

galaxybrain_help, galaxybrain_watch, and galaxybrain_update do not use output modes.

Instances

A GalaxyBrain instance is a browser tab connected to the API server.

Routing rules

• One instance connected — instance is optional; auto-routed.
• Multiple instances — instance is required. Use galaxybrain_status to list them.
• No instances — commands fail with NO_INSTANCES. Open GalaxyBrain in a browser.

Versions & Conflict Detection

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

• Match — mutation proceeds.
• Mismatch — CONFLICT error. Re-read and retry.
• Omitted — conflict check is skipped.

Where readVersion goes

Event Watching

The galaxybrain_watch tool sets up real-time event monitoring. It returns a shell command to run with your AI tool's process monitor. Each matching event prints a line to stdout.

Event Types

Page events

Workspace events

Project events

project_opened, project_closed, concurrent_access_detected

File events

files_changed — fires for each filesystem change produced by an active FILES_WATCH subscription (see File Watching below).

File Watching

File watching lets you drive agents off filesystem activity inside your GalaxyBrain project folder, not just app-internal mutations. It's a thin wrapper around Chromium's FileSystemObserver, exposed through the same monitor script as everything else in galaxybrain_watch.

Typical uses:

• Inbox processing. Drop a PDF into inbox/, have the agent OCR it, write a page, move the file to inbox/processed/.
• External edit sync. Watch a subfolder you also edit outside GalaxyBrain and reconcile changes back into pages.
• Attachment pipelines. React when images, audio, or exports land in a known drop folder — e.g. transcribe voice memos, tag screenshots, thumbnail photos.
• Cleanup / audit. Alert on unexpected deletions or moves inside critical folders.

Pass files_subscriptions to galaxybrain_watch to start one or more folder watches when the monitor connects. Each entry fires a FILES_WATCH against the open instance before the monitor subscribes to the event stream:

{
  "files_subscriptions": [
    { "subpath": "inbox", "recursive": true }
  ]
}

subpath is forward-slash-delimited and must resolve to an existing directory under the project root. Leading /, backslashes, Windows-absolute paths, .., ., and empty segments are rejected. recursive defaults to false — without it you only see direct children of the folder.

Each change produces one files_changed stdout line carrying subscriptionId, subpath, recursive, changeType, path (array, relative to subpath), and movedFrom (array on moved, null otherwise). Change types mirror the platform API:

Use files_change_types to narrow the stream to the records you care about:

{
  "files_subscriptions": [{ "subpath": "inbox", "recursive": true }],
  "files_change_types": ["appeared", "moved"]
}

File watches fail with specific wire errors you may need to handle:

• FOLDER_UNAVAILABLE — the open project is a demo / in-memory, so there's no real folder to observe.
• UNSUPPORTED_BROWSER — the browser doesn't expose FileSystemObserver (currently Chromium-only).
• FOLDER_NOT_FOUND — the subpath doesn't resolve to an existing directory under the project root.
• NO_PROJECT — no project is open.

Built-in filter: files_changed events whose last path segment is .DS_Store are dropped before emission — macOS metadata noise is never forwarded to the agent.

Other sharp edges: Windows reports cross-directory moves as a disappeared+appeared pair rather than a single moved record. File events are not file-readiness events — a large file copy produces appeared (and possibly modified) before the writer has finished, so use temp-then-rename or wait for size/mtime stability if completion matters. Per-origin observation limits are OS-dependent and surface as errored.

Content Filters

Content filters detect specific changes within pages_updated events by comparing before/after state. Each filter has a required type field and optional scoping.

Block-level filters

Support pageIds and blockId scoping:

Page-level filters

Support pageIds scoping:

Hooks

Hooks are optional JavaScript/TypeScript modules that run on each matched event before it reaches the agent. They can perform side effects, suppress events (return false), or replace the output (return a string).

// update-subtitle-hook.ts
export default async function(match, context) {
  if (match.output.filter === "checked_count_changed"
      && match.output.afterChecked > match.output.beforeChecked) {
    await context.sendCommand("UPDATE_PAGES", {
      pages: [{ pageId: match.output.pageId,
        subtitle: [{ type: "text", text: "Processing..." }] }]
    });
  }
}

Return values

• undefined — event passes through normally
• false — event is suppressed (agent is not woken)
• string — replaces the default output (agent sees your string)

Use hook_debug: true for verbose tracing of all hook calls.

Error Reference

Routing errors

Command errors

Troubleshooting

Prerequisites

GalaxyBrain MCP requires Bun. Install:

• macOS/Linux: curl -fsSL https://bun.sh/install | bash
• Windows: powershell -c "irm bun.sh/install.ps1 | iex"

After installing, fully quit your MCP host and relaunch it from a fresh terminal where bun --version works — the host inherits PATH from the terminal that launched it, not from ~/.zshrc or ~/.bashrc.

If Bun is installed at an unusual path, set GB_BUN_PATH to its absolute path in the host's environment.

Recommended Setup

Configure your MCP client with:

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

The -y flag auto-confirms the install prompt. Without it, npx may hang waiting for confirmation since MCP servers have no interactive terminal.

Updating

The MCP server checks for updates on startup and re-checks lazily during long sessions. When an update is available, the notice is prepended to galaxybrain_status, galaxybrain_orient, and galaxybrain_help output; agents can also detect it programmatically via galaxybrain_status raw output (mcp.updateAvailable === true).

Agents should prefer calling galaxybrain_update — it warms the npx cache without requiring the user to drop to a shell. After it reports success, the user must restart their MCP host for the new version to take effect. The shell equivalent is:

npx -y galaxybrain-mcp@latest

To update the API server:

npx -y galaxybrain-api@latest

If an old API server is still running, stop it first:

lsof -ti :1924 | xargs kill

npx Caching

npx caches packages locally. Running npx -y galaxybrain-mcp uses the cached version without checking for updates — this keeps startup fast. To force an update, run npx -y galaxybrain-mcp@latest once. Subsequent runs use the updated cache.

Do not use @latest in your MCP client configuration — it causes a network request to the npm registry on every startup, adding latency.

Version Mismatches

The browser app, API server, and MCP server share a protocol version. When versions don't match:

• MCP ↔ API server — The MCP server checks protocol compatibility before connecting. Incompatible versions produce a clear error with update instructions.
• Browser app ↔ API server — The app checks on WebSocket connect. Incompatible versions show a warning toast with update instructions.

Common Errors

Further Reading

• GalaxyBrain API Reference — full WebSocket API with transport details, data model schemas, and all command specifications.
• galaxybrain_help tool — call it from your AI tool for detailed, contextual documentation during a session.