Skip to main content
Glama
Sign In
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

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.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
    9
    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