Skip to main content
Glama
yannisgu

companion-mcp-server

by yannisgu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Companion MCP 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

Related MCP server: Companion MCP

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

License

MIT

This server cannot be deployed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Companion MCP

    drohi-r
    A
    license
    B
    quality
    D
    maintenance
    An MCP server for Bitfocus Companion that enables AI assistants to program and control Stream Deck surfaces and other Companion-connected devices. It provides 53 tools for button control, styling, page management, variable handling, and batch operations with verification and rollback.
    53
    6
    Apache 2.0

  • bika-mcp

    hamchowderr
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server for integrating with Bika.ai platform, enabling AI assistants to perform CRUD operations on databases, manage attachments, and utilize automation and webhooks.
    1
    MIT