Skip to main content
Glama
Companion MCP
by drohi-r

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: GMA2 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

Variable

Default

Description

COMPANION_HOST

127.0.0.1

Companion instance IP

COMPANION_PORT

8000

Companion HTTP and websocket port

COMPANION_TIMEOUT_S

10.0

HTTP request timeout in seconds

COMPANION_ALLOWED_HOSTS

127.0.0.1,localhost,::1

Comma-separated allowlist for target hosts. Set * to allow any.

COMPANION_WRITE_ENABLED

1

Set to 0 for read-only mode

COMPANION_TRANSPORT

stdio

MCP transport (stdio, sse, streamable-http)

COMPANION_UI_HOST

127.0.0.1

Browser UI bind address

COMPANION_UI_PORT

8088

Browser UI port

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.

Tool

What it does

get_server_config

Return current MCP server configuration and safety settings

health_check

Probe Companion API reachability and return status

list_surfaces

List connected control surfaces (Stream Deck, etc.)

get_button_info

Read the current control and preview state for a specific button

get_button_runtime_summary

Return a compact operator-oriented runtime summary for a button

get_page_grid

Read a rectangular grid of buttons from a page

snapshot_page_inventory

Export a page region with concise button summaries, style, feedback, and preview hashes

save_page_inventory_snapshot

Save a named page inventory checkpoint to disk

load_page_inventory_snapshot

Load a saved page inventory checkpoint from disk

list_page_inventory_snapshots

List saved page inventory checkpoint files

delete_page_inventory_snapshot

Delete a saved page inventory checkpoint file

diff_page_inventory

Compare two page inventory snapshots and summarize changed buttons

preview_restore_page_style_from_inventory

Turn a saved inventory snapshot into a restore plan without writing to Companion

preview_restore_page_style_from_snapshot

Preview a restore plan from a named saved snapshot

save_page_style_preset

Save current page style entries as a reusable preset

load_page_style_preset

Load a saved page style preset

list_page_style_presets

List saved page style presets

delete_page_style_preset

Delete a saved page style preset

preview_apply_page_style_preset

Preview applying a saved page style preset with optional offsets

find_buttons

Search a page region by visible text, control id, control type, connection id, or definition id

export_page_layout

Export a page region as a reusable layout payload

get_custom_variable

Read a Companion custom variable

get_module_variable

Read a variable from a Companion module connection

snapshot_custom_variables

Read a named list of custom variables in one call

verify_button_render_change

Compare a current button preview hash to a previous one

Preview (plan before you write)

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

Tool

What it does

preview_page_style

Validate and preview a page-style batch

preview_label_button_grid

Resolve a label grid into coordinates

preview_button_template

Place a reusable template at an origin and preview the result

Button actions

Require COMPANION_WRITE_ENABLED=1 (default).

Tool

What it does

press_button

Press and release a button

press_button_verified

Press a button and poll for visible/runtime state change

hold_button

Press and hold (down actions only)

release_button

Release a held button (up actions)

rotate_left

Rotate encoder left

rotate_right

Rotate encoder right

set_step

Set the current action step

Button styling

Tool

What it does

set_button_text

Change button display text

set_button_color

Change text and/or background color (6-digit hex)

set_button_style

Set multiple style properties at once

set_button_style_verified

Apply style changes and poll until the render catches up or the timeout expires

Batch operations

Tool

What it does

press_button_sequence

Press multiple buttons in order with configurable delay

set_page_style

Batch-set style on multiple buttons on a page

set_page_style_verified

Batch-set styles on a page and return per-button verification plus an inventory diff

restore_page_style_from_inventory

Restore button styles from a previously captured page inventory

restore_selected_page_style_from_inventory

Restore only selected coordinates from an inventory snapshot

restore_page_style_from_snapshot

Restore styles from a named saved snapshot

apply_page_style_transaction

Save a rollback checkpoint, apply verified styles, and return rollback metadata

rollback_page_style_transaction

Roll back a named transaction snapshot

apply_page_style_preset

Apply a saved page style preset with optional offsets

label_button_grid

Label a grid of buttons from a flat list of names

apply_button_template

Apply a reusable button template at a page origin

Variables and system

Tool

What it does

set_custom_variable

Write a Companion custom variable

rescan_surfaces

Rescan connected USB surfaces

press_bank_button

Legacy bank API (deprecated, still works)

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

Available Tools

53 tools
apply_button_templateC

Apply a reusable button template at an origin on a page.

Inputs: page (required), template_json (required), origin_row, origin_column. Returns: result

apply_page_style_presetC

Apply a saved page style preset with optional page override and coordinate offsets.

Inputs: name (required), page, origin_row, origin_column, +2 more. Returns: result

apply_page_style_transactionC

Save a rollback checkpoint, apply verified page style changes, and return the checkpoint metadata.

Inputs: snapshot_name (required), page (required), buttons_json (required), rows, +4 more. Returns: result

delete_page_inventory_snapshotC

Delete a saved page inventory snapshot file.

Inputs: name (required). Returns: result

delete_page_style_presetC

Delete a saved page style preset file.

Inputs: name (required). Returns: result

diff_page_inventoryC

Compare two page inventory snapshots and summarize added, removed, and changed buttons.

Inputs: before_inventory_json (required), after_inventory_json (required). Returns: result

export_page_layoutC

Export a page region as a reusable layout payload.

Inputs: page (required), rows, columns, include_empty. Returns: result

find_buttonsC

Find buttons by text, control id, control type, or integration metadata within a page region.

Inputs: query, page, rows, columns, +4 more. Returns: result

get_button_infoB

Fetch the current control state and rendered preview metadata for a Companion button location.

Inputs: page (required), row (required), column (required). Returns: result

get_button_runtime_summaryC

Return a compact runtime-oriented summary for a button.

Inputs: page (required), row (required), column (required). Returns: result

get_custom_variableC

Get the value of a Companion custom variable.

Inputs: name (required). Returns: result

get_module_variableC

Get a module variable value from a named Companion connection.

Inputs: connection (required), name (required). Returns: result

get_page_gridB

Read a rectangular grid of button payloads for a page.

Inputs: page (required), rows, columns, include_empty. Returns: result

get_server_configA

Return the current Companion MCP server configuration.

Inputs: no named parameters. Returns: result

health_checkA

Probe Companion reachability and return API status details.

Inputs: no named parameters. Returns: result

hold_buttonA

Press and hold a button (runs down actions only). Use release_button to let go.

Inputs: page (required), row (required), column (required). Returns: result

label_button_gridA

Label a grid of buttons from a flat list of names.

Fills left-to-right, top-to-bottom. Empty strings skip that position. labels_json: JSON array of strings, e.g. ["GO", "STOP", "", "BLACKOUT"] columns: buttons per row (default 8, use 5 for standard Stream Deck).

Inputs: page (required), labels_json (required), columns. Returns: result

list_page_inventory_snapshotsA

List saved page inventory snapshot files.

Inputs: no named parameters. Returns: result

list_page_style_presetsA

List saved page style preset files.

Inputs: no named parameters. Returns: result

list_surfacesA

List connected Companion control surfaces.

Inputs: no named parameters. Returns: result

load_page_inventory_snapshotC

Load a previously saved page inventory snapshot from disk.

Inputs: name (required). Returns: result

load_page_style_presetC

Load a saved page style preset file.

Inputs: name (required). Returns: result

press_bank_buttonA

Press a button using the legacy bank API (deprecated but still works). button is 0-indexed.

Inputs: page (required), button (required). Returns: result

press_buttonB

Press and release a button (runs both down and up actions).

Inputs: page (required), row (required), column (required). Returns: result

press_button_sequenceA

Press multiple buttons in sequence with a configurable delay between each.

buttons_json: JSON array of {page, row, column} objects. delay_ms: milliseconds to wait between presses (default 100).

Inputs: buttons_json (required), delay_ms. Returns: result

press_button_verifiedB

Press a button and verify whether its visible or runtime state changed.

Inputs: page (required), row (required), column (required), wait_ms, +1 more. Returns: result

preview_apply_page_style_presetA

Preview applying a saved preset onto a page, optionally with row/column offsets.

Inputs: name (required), page, origin_row, origin_column. Returns: result

preview_button_templateC

Preview a reusable button template placed at an origin on a page.

Inputs: page (required), template_json (required), origin_row, origin_column. Returns: result

preview_label_button_gridC

Resolve a label grid into coordinates without writing to Companion.

Inputs: page (required), labels_json (required), columns. Returns: result

preview_page_styleC

Validate and preview a batch page-style operation without writing to Companion.

Inputs: page (required), buttons_json (required). Returns: result

preview_restore_page_style_from_inventoryA

Resolve a captured page inventory into restore-style entries without writing to Companion.

Inputs: inventory_json (required). Returns: result

preview_restore_page_style_from_snapshotB

Preview a restore plan from a saved snapshot, optionally filtered to selected coordinates.

Inputs: name (required), coords_json. Returns: result

release_buttonA

Release a held button (runs up actions).

Inputs: page (required), row (required), column (required). Returns: result

rescan_surfacesA

Rescan for connected USB surfaces (Stream Deck, etc.).

Inputs: no named parameters. Returns: result

restore_page_style_from_inventoryC

Restore button style state from a previously captured page inventory.

Inputs: inventory_json (required), wait_ms, poll_ms. Returns: result

restore_page_style_from_snapshotC

Restore button style state from a saved snapshot file, optionally filtered to selected coordinates.

Inputs: name (required), wait_ms, poll_ms, coords_json. Returns: result

restore_selected_page_style_from_inventoryC

Restore only selected coordinates from a captured page inventory.

Inputs: inventory_json (required), coords_json (required), wait_ms, poll_ms. Returns: result

rollback_page_style_transactionC

Rollback page styles from a saved transaction snapshot.

Inputs: snapshot_name (required), wait_ms, poll_ms, coords_json. Returns: result

rotate_leftC

Trigger a left rotation on an encoder button.

Inputs: page (required), row (required), column (required). Returns: result

rotate_rightC

Trigger a right rotation on an encoder button.

Inputs: page (required), row (required), column (required). Returns: result

save_page_inventory_snapshotC

Capture a page inventory snapshot and save it to a local checkpoint file.

Inputs: name (required), page (required), rows, columns, +1 more. Returns: result

save_page_style_presetC

Save the current page style state as a reusable preset file.

Inputs: name (required), page (required), rows, columns, +1 more. Returns: result

set_button_colorB

Change button colors. Use 6-digit hex (e.g. 'ff0000' for red). color=text color, bgcolor=background color.

Inputs: page (required), row (required), column (required), color, +1 more. Returns: result

set_button_styleA

Set multiple button style properties at once. All parameters optional — only provided values are changed.

Inputs: page (required), row (required), column (required), text, +3 more. Returns: result

set_button_style_verifiedC

Apply button style changes and verify whether the rendered button output actually changed.

Inputs: page (required), row (required), column (required), text, +5 more. Returns: result

set_button_textC

Change the text displayed on a button.

Inputs: page (required), row (required), column (required), text (required). Returns: result

set_custom_variableB

Set the value of a Companion custom variable.

Inputs: name (required), value (required). Returns: result

set_page_styleC

Batch-set style on multiple buttons on a page.

buttons_json: JSON array of {row, column, text?, color?, bgcolor?} objects.

Inputs: page (required), buttons_json (required). Returns: result

set_page_style_verifiedC

Batch-set styles on a page and return verified per-button outcomes plus an inventory diff.

Inputs: page (required), buttons_json (required), wait_ms, poll_ms. Returns: result

set_stepC

Set the current step of a button action sequence.

Inputs: page (required), row (required), column (required), step (required). Returns: result

snapshot_custom_variablesC

Read a named set of custom variables into one snapshot payload.

Inputs: names_json (required). Returns: result

snapshot_page_inventoryC

Export a page region with operator-focused button summaries, hashes, style, and feedback state.

Inputs: page (required), rows, columns, include_empty. Returns: result

verify_button_render_changeC

Compare the current button preview fingerprint to a previous preview hash.

Inputs: page (required), row (required), column (required), previous_sha256 (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 53 tools

    Disambiguation4/5

    Most tools have distinct purposes with clear descriptions (e.g., press vs hold vs release, various preview vs apply pairs). A few pairs like apply_button_template and apply_page_style_preset could be confused at a glance, but descriptions clarify the differing targets (template vs preset). Overall, an agent can reliably distinguish tools.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., press_button, set_button_color, list_surfaces). Even variations like hold_button and rotate_right fit the pattern. There is no mixing of conventions, making the set predictable.

    Tool Count2/5

    With 53 tools, the server is over-scoped. Many tools are variations (e.g., press, press_verified, press_sequence; set_style, set_style_verified) which could be consolidated. While the domain is rich, this number exceeds typical MCP server sizes and may overwhelm agents.

    Completeness5/5

    The surface covers all major aspects of Companion management: button actions, style editing, presets, snapshots, variables, surfaces, rollbacks, and verification. No obvious gaps remain; even encoder rotation and transaction rollback are present.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      An MCP server that lets AI assistants control grandMA2 lighting consoles via Telnet, exposing 41 high-level tools for cue management, fixture control, preset management, executor control, macro editing, appearance assignment, bulk operations, console state queries, show file management, read-back verification, and music show workflows.
      100
      20
      Apache 2.0