Companion Server

An MCP (Model Context Protocol) server for Bitfocus Companion, enabling AI assistants to control buttons, triggers, variables, and connections.

Features

• Connections: List connections and their action/feedback definitions
• Variables: List, search, get values, create and set custom variables
• Pages & Buttons: Create, configure, and press buttons with actions and feedbacks
• Triggers: Create, clone, update, and batch-update triggers with full support for events, conditions, actions, and collections

Installation

No installation required - run directly with npx:

npx companion-mcp-server [companion-url]

Or install globally:

npm install -g companion-mcp-server

Configuration

Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "companion": {
      "command": "npx",
      "args": ["-y", "companion-mcp-server", "http://localhost:8889"]
    }
  }
}

Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "companion": {
      "command": "npx",
      "args": ["-y", "companion-mcp-server", "http://localhost:8889"]
    }
  }
}

Or add to a project-specific .claude/settings.json in your project root.

Cursor

Add to Cursor's MCP configuration (~/.cursor/mcp.json):

{
  "mcpServers": {
    "companion": {
      "command": "npx",
      "args": ["-y", "companion-mcp-server", "http://localhost:8889"]
    }
  }
}

Windsurf

Add to Windsurf's MCP configuration (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "companion": {
      "command": "npx",
      "args": ["-y", "companion-mcp-server", "http://localhost:8889"]
    }
  }
}

Custom Companion URL

Replace http://localhost:8889 with your Companion instance URL if it's running on a different host or port:

"args": ["-y", "companion-mcp-server", "http://192.168.1.100:8889"]

Environment Variable

You can also set the URL via environment variable:

{
  "mcpServers": {
    "companion": {
      "command": "npx",
      "args": ["-y", "companion-mcp-server"],
      "env": {
        "COMPANION_URL": "http://localhost:8889"
      }
    }
  }
}

Available Tools

Variables

Tool	Description
list_variables	List all variable definitions grouped by connection
search_variables	Search variables by name/label pattern
get_variable_value	Get a variable's current value
create_custom_variable	Create a new custom variable
set_custom_variable	Set a custom variable's value

Connections

Tool	Description
list_connections	List all configured connections with IDs and status
list_connection_definitions	Get action/feedback definitions for a connection

Pages & Buttons

Tool	Description
list_pages	List all pages with their button grids
create_page	Create new page(s) at a position
remove_page	Delete a page and all its controls
set_page_name	Rename a page
move_page	Move a page to a different position
clear_page	Reset a page to defaults
get_button	Get a button's full configuration
create_button	Create a new button at a location
delete_button	Delete a button
update_button	Update button style, actions, and feedbacks
press_button	Simulate button press/release

Triggers

Tool	Description
list_triggers	List all triggers with collection info
list_trigger_collections	List all trigger collections
get_trigger	Get a trigger's full configuration
create_trigger	Create a trigger with optional inline config
clone_trigger	Clone an existing trigger with option overrides
update_trigger	Update a trigger with multiple operations
batch_update_triggers	Bulk update multiple triggers
create_trigger_collection	Create a trigger collection
delete_trigger	Delete a trigger

Resources

The server exposes MCP resources for quick context:

Resource	Description
companion://guide	Usage guide for the MCP tools
companion://connections	Summary of configured connections
companion://presets	Available button presets by connection

Examples

Create a button that switches to camera 1

1. Use list_connections to find your ATEM connection ID
2. Use list_connection_definitions with that ID to find the "program" action
3. Use create_button to create a button at page 1, row 0, column 0
4. Use update_button with set_style (text: "CAM 1") and add_action (the program action with input: 1)

Clone triggers for multiple cameras

1. Use get_trigger to inspect an existing camera trigger
2. Use clone_trigger with the source trigger ID, new name, and optionOverrides to change the camera number
3. Repeat for each camera, or use batch_update_triggers for bulk operations

Search for tally variables

Use search_variables with query "tally" to find all tally-related variables across connections

Development

# Clone the repo
git clone https://github.com/yannisgu/companion-mcp-server.git
cd companion-mcp-server

# Install dependencies
yarn install

# Run in development mode
yarn dev

# Build for production
yarn build:ts

Requirements

• Node.js 18+
• A running Bitfocus Companion instance

License

MIT