Companion MCP

Built for the show floor

It covers every command in Companion's documented HTTP API: read variables and connection status, press and rotate allowlisted buttons, set steps and styles, and restart, enable or disable connections.

The AI sees why

A refusal comes back as a plain reason, never a stack trace, so the assistant can tell you which gate stopped it and what to change.

Every call on the record

One JSON line per tool call in logs/companion-mcp.jsonl, with attempt, ok, refused and error outcomes, redacted variable values, mode 0600 and a 5 MB rotation.

Read-only until you say so

Nothing is written unless COMPANION_ALLOW_WRITES is true, and every write reports what it would send unless the AI passes dry_run: false.

An allowlist is the boundary

Only buttons, variables and connections you list can be written. Anything else is refused, whatever the AI asks.

Confirm for high risk

Buttons you mark high risk, and every connection or config edit, also need confirm: true.

One attempt, no retries

On a timeout, reset or server error it reports outcome unknown instead of guessing or retrying, so a button is never fired twice.

Audit log first

An attempt line is written before every real write. If the log cannot be written, writes are refused.

Private network only

It refuses a public address unless COMPANION_ALLOW_REMOTE is true, and it opens no ports: your AI client launches it over stdio.

Read tools

• ping Liveness; reports write and config-edit state without touching Companion.
• list_allowlist Shows everything the write tools may touch.
• get_custom_variable Read a $(custom:name) value.
• get_module_variable Read a $(label:name) value from a connection.
• list_connections All connections with id, module and status.
• get_connection_status One connection by id.

Write tools

These need writes enabled, an allowlist entry and, for high-risk buttons, confirm: true.

• press_button Press and release an allowlisted button.
• button_action down, up, rotate_left or rotate_right on an allowlisted button.
• set_button_step Set the current step of a multi-step button.
• set_button_style Change text, text colour, background colour or size.
• set_custom_variable Set an allowlisted custom variable.
• connection_action restart, enable or disable an allowlisted connection; needs confirm: true.
• rescan_surfaces Rescan for USB surfaces; needs surfaces_rescan enabled.