Companion MCP

An MCP server for Bitfocus Companion. Exposes 53 tools covering verified button control, styling, page discovery, runtime summaries, inventory diffing, checkpointed rollback/restore workflows, preset management, variable management, and batch show programming — so AI assistants can operate Stream Deck surfaces and other Companion-connected devices through Companion's current APIs.

Built for live production. Pairs with grandMA2 MCP, Resolume MCP, MADRIX MCP, and Beyond MCP for full AI-driven show control.

The repo also includes a lightweight local browser UI for humans who want the same verified flows without manually issuing MCP tool calls.

Why this exists

Companion is the physical button layer that ties a live production stack together. An operator presses a Stream Deck button and it fires a grandMA2 cue, triggers a Resolume clip, or starts a laser sequence. But programming those buttons is manual — you click through the Companion UI, one button at a time, configuring actions, labels, and colors.

This MCP server lets an AI do that work. It can read your current button layout, preview changes before applying them, and batch-program entire pages in seconds. Combined with MA2 Agent and Resolume MCP, an AI assistant can program the entire show control surface from a single conversation.

Related MCP server: touch-mcp

Quick start

git clone https://github.com/drohi-r/companion-mcp && cd companion-mcp
uv sync
uv run python -m companion_mcp

Browser UI

Run the local operator UI:

uv run companion-mcp-ui

Then open:

http://127.0.0.1:8088

The UI is intentionally local-first. It sits on top of the same backend logic as the MCP tools, so verified writes, snapshots, presets, and rollback behave the same in the browser as they do through MCP.

Make sure Companion is running on the target host and port. Current Companion builds use:

• HTTP endpoints for button actions and style writes

• websocket tRPC at /trpc for richer reads, discovery, preview, and variable inspection

Configuration

Architecture

graph TD
    A["Companion MCP Server<br/><code>companion_mcp</code><br/>53 tools · safety gate"] --> B
    B["HTTP Client<br/>Button actions · style writes"] --> D
    A --> C
    C["WebSocket tRPC Client<br/>Discovery · preview · variables"] --> D
    D["Bitfocus Companion<br/>HTTP + WebSocket at /trpc"]

    E["Browser UI<br/><code>companion-mcp-ui</code><br/>Local operator console"] -.-> A
    F["Snapshot Engine<br/>Inventory · presets · rollback"] -.-> A
    G["Verification Layer<br/>Render polling · diff · transactions"] -.-> A

    style A fill:#1a1a2e,stroke:#14B8A6,color:#fff
    style B fill:#1a1a2e,stroke:#14B8A6,color:#fff
    style C fill:#1a1a2e,stroke:#14B8A6,color:#fff
    style D fill:#1a1a2e,stroke:#0f3460,color:#fff
    style E fill:#0f3460,stroke:#0f3460,color:#fff
    style F fill:#0f3460,stroke:#0f3460,color:#fff
    style G fill:#0f3460,stroke:#0f3460,color:#fff

Tools

Discovery and reads

Safe, read-only tools for understanding the current state of Companion.

Preview (plan before you write)

Validate and preview operations without touching Companion. Use these to inspect what a batch operation will do before committing.

Button actions

Require COMPANION_WRITE_ENABLED=1 (default).

Button styling

Batch operations

Variables and system

Claude Desktop

{
  "mcpServers": {
    "companion": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/companion-mcp", "python", "-m", "companion_mcp"],
      "env": {
        "COMPANION_HOST": "127.0.0.1",
        "COMPANION_PORT": "8000"
      }
    }
  }
}

VS Code / Cursor

{
  "servers": {
    "companion": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/companion-mcp", "python", "-m", "companion_mcp"],
      "env": {
        "COMPANION_HOST": "127.0.0.1",
        "COMPANION_PORT": "8000"
      }
    }
  }
}

Codex

Create a codex.json MCP config file:

{
  "mcpServers": {
    "companion": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/companion-mcp", "python", "-m", "companion_mcp"],
      "env": {
        "COMPANION_HOST": "127.0.0.1",
        "COMPANION_PORT": "8000"
      }
    }
  }
}

Then run Codex with:

codex --mcp-config codex.json

Production safety

This server is designed for live show environments where accidental writes can disrupt a running production.

• Host allowlisting — only 127.0.0.1, localhost, and ::1 are permitted by default. Add LAN hosts explicitly via COMPANION_ALLOWED_HOSTS.

• Write gating — set COMPANION_WRITE_ENABLED=0 to block all write operations. Read and preview tools remain available.

• Preview before apply — every batch operation has a corresponding preview tool that validates inputs and shows exactly what will change, without touching Companion.

• Verified writes — prefer press_button_verified and set_button_style_verified when you care about actual visible or runtime state changes, not just HTTP acceptance.

• Snapshot and diff workflow — use snapshot_page_inventory before and after batch changes, or let set_page_style_verified produce an inventory diff automatically.

• Rollback path — capture a page with snapshot_page_inventory or save_page_inventory_snapshot, inspect the restore plan with preview_restore_page_style_from_inventory or preview_restore_page_style_from_snapshot, then use the matching restore tool to roll styles back cleanly.

• Transaction flow — apply_page_style_transaction creates a named rollback checkpoint before it writes. rollback_page_style_transaction restores from that named snapshot.

• Preset workflow — save reusable page styles with save_page_style_preset, inspect with preview_apply_page_style_preset, and deploy with apply_page_style_preset.

• Input validation — page, row, column, color hex, delay bounds, and template structure are all validated before any API call is made. Invalid inputs return structured JSON errors, never raw exceptions.

• Error isolation — all tools are wrapped in _handle_errors. Network failures, JSON parse errors, and validation failures return {"ok": false, "error": "...", "blocked": true} instead of crashing the MCP session.

Live behavior notes

• A successful HTTP write does not always mean the button visibly changed immediately.

• Current Companion builds can update stored style state first, then repaint the preview a short time later.

• set_button_style_verified and press_button_verified include bounded polling so the MCP can distinguish:

  • write accepted but nothing observable changed

  • write accepted and the preview changed after a short delay

  • write accepted and style state changed, but visible render still did not change

Why the UI helps

The MCP backend is already the real product. The UI does not replace it; it makes it faster and safer for humans:

• click buttons in a page grid instead of remembering page,row,column

• inspect preview, style, runtime summary, and the last verified response in one place

• save and browse snapshots and presets without opening JSON files

• run verified style changes and transaction rollback from a browser during show prep

• hand the system to an operator who is not going to type MCP calls by hand

Development

uv sync
uv run python -m pytest -v

License

Apache 2.0