Companion MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Companion MCP Set button 3 on page 1 to blue with label 'Next'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_mcpBrowser UI
Run the local operator UI:
uv run companion-mcp-uiThen open:
http://127.0.0.1:8088The 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
/trpcfor richer reads, discovery, preview, and variable inspection
Configuration
Variable | Default | Description |
|
| Companion instance IP |
|
| Companion HTTP and websocket port |
|
| HTTP request timeout in seconds |
|
| Comma-separated allowlist for target hosts. Set |
|
| Set to |
|
| MCP transport ( |
|
| Browser UI bind address |
|
| 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:#fffTools
Discovery and reads
Safe, read-only tools for understanding the current state of Companion.
Tool | What it does |
| Return current MCP server configuration and safety settings |
| Probe Companion API reachability and return status |
| List connected control surfaces (Stream Deck, etc.) |
| Read the current control and preview state for a specific button |
| Return a compact operator-oriented runtime summary for a button |
| Read a rectangular grid of buttons from a page |
| Export a page region with concise button summaries, style, feedback, and preview hashes |
| Save a named page inventory checkpoint to disk |
| Load a saved page inventory checkpoint from disk |
| List saved page inventory checkpoint files |
| Delete a saved page inventory checkpoint file |
| Compare two page inventory snapshots and summarize changed buttons |
| Turn a saved inventory snapshot into a restore plan without writing to Companion |
| Preview a restore plan from a named saved snapshot |
| Save current page style entries as a reusable preset |
| Load a saved page style preset |
| List saved page style presets |
| Delete a saved page style preset |
| Preview applying a saved page style preset with optional offsets |
| Search a page region by visible text, control id, control type, connection id, or definition id |
| Export a page region as a reusable layout payload |
| Read a Companion custom variable |
| Read a variable from a Companion module connection |
| Read a named list of custom variables in one call |
| 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 |
| Validate and preview a page-style batch |
| Resolve a label grid into coordinates |
| Place a reusable template at an origin and preview the result |
Button actions
Require COMPANION_WRITE_ENABLED=1 (default).
Tool | What it does |
| Press and release a button |
| Press a button and poll for visible/runtime state change |
| Press and hold (down actions only) |
| Release a held button (up actions) |
| Rotate encoder left |
| Rotate encoder right |
| Set the current action step |
Button styling
Tool | What it does |
| Change button display text |
| Change text and/or background color (6-digit hex) |
| Set multiple style properties at once |
| Apply style changes and poll until the render catches up or the timeout expires |
Batch operations
Tool | What it does |
| Press multiple buttons in order with configurable delay |
| Batch-set style on multiple buttons on a page |
| Batch-set styles on a page and return per-button verification plus an inventory diff |
| Restore button styles from a previously captured page inventory |
| Restore only selected coordinates from an inventory snapshot |
| Restore styles from a named saved snapshot |
| Save a rollback checkpoint, apply verified styles, and return rollback metadata |
| Roll back a named transaction snapshot |
| Apply a saved page style preset with optional offsets |
| Label a grid of buttons from a flat list of names |
| Apply a reusable button template at a page origin |
Variables and system
Tool | What it does |
| Write a Companion custom variable |
| Rescan connected USB surfaces |
| 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.jsonProduction 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::1are permitted by default. Add LAN hosts explicitly viaCOMPANION_ALLOWED_HOSTS.Write gating — set
COMPANION_WRITE_ENABLED=0to 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_verifiedandset_button_style_verifiedwhen you care about actual visible or runtime state changes, not just HTTP acceptance.Snapshot and diff workflow — use
snapshot_page_inventorybefore and after batch changes, or letset_page_style_verifiedproduce an inventory diff automatically.Rollback path — capture a page with
snapshot_page_inventoryorsave_page_inventory_snapshot, inspect the restore plan withpreview_restore_page_style_from_inventoryorpreview_restore_page_style_from_snapshot, then use the matching restore tool to roll styles back cleanly.Transaction flow —
apply_page_style_transactioncreates a named rollback checkpoint before it writes.rollback_page_style_transactionrestores from that named snapshot.Preset workflow — save reusable page styles with
save_page_style_preset, inspect withpreview_apply_page_style_preset, and deploy withapply_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_verifiedandpress_button_verifiedinclude 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,columninspect 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 -vLicense
Available Tools
53 toolsapply_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
Scored across 53 tools
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.
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.
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.
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
Related MCP Connectors
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- AlicenseBqualityCmaintenanceThe most capable MCP server for Final Cut Pro — 88 tools covering FCPXML editing, live FCP control, parametric puppets, and media analysis.88187 PyPI12MIT
- AlicenseBqualityCmaintenanceAn 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.10020Apache 2.0
- AlicenseCqualityAmaintenanceA comprehensive MCP server that enables AI assistants to control REAPER DAW for mixing, mastering, MIDI composition, and full music production workflows with 130 tools.1872,076 PyPI114MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Bitfocus Companion, enabling AI assistants to control buttons, triggers, variables, and connections.12 npm5MIT