Skip to main content
Glama
yannisgu

companion-mcp-server

by yannisgu
OverviewSchemaRelated ServersScoreDiscussions
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: hass-mcp-server

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 installed

A
license - permissive license
-
quality - not tested
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/yannisgu/companion-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server