home / mcp / stream deck mcp server

Stream Deck MCP Server

Provides a local MCP server to program Stream Deck buttons and pages via AI-driven workflows.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "verygoodplugins-streamdeck-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/streamdeck-mcp",
        "run",
        "server.py"
      ],
      "env": {
        "UV_HOME": "~/.uv"
      }
    }
  }
}

This MCP server lets you control the Stream Deck locally from an AI-enabled workflow. It connects to your Stream Deck hardware, lets you define pages and buttons, and applies changes automatically so you can design complex layouts and actions with simple prompts.

How to use

You run the MCP server locally and connect it to your Stream Deck. Use an MCP client to issue commands that connect to the server, create pages, and configure buttons. Typical workflows include creating a dedicated page for a project, assigning button actions, and switching between pages as your setup evolves.

How to install

Follow these concrete steps to install and run the MCP server on your machine.

# Prerequisites
# macOS
brew install hidapi

# Linux (Debian/Ubuntu)
sudo apt install libhidapi-libusb0

# Linux udev rule (required for non-root access)
sudo tee /etc/udev/rules.d/10-streamdeck.rules << EOF
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0fd9", GROUP="users", MODE="0666"
EOF
sudo udevadm control --reload-rules

Install the MCP server by cloning the repository, setting up a Python environment, and installing the package in editable mode.

git clone https://github.com/verygoodplugins/streamdeck-mcp.git
cd streamdeck-mcp
uv venv && uv pip install -e .

Add the MCP server to Claude Desktop configuration to enable the integration.

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

{
  "mcpServers": {
    "streamdeck": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/streamdeck-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

Start using the server by issuing a connect command in your MCP client, then configure buttons and pages as needed.

Configuration and usage notes

Important: Quit the Elgato Stream Deck software before using this MCP server. The server requires exclusive USB access, so only one application may control the Stream Deck at a time.

# macOS — quit Elgato software
killall "Stream Deck" 2>/dev/null || true

The server includes a set of tools to manage your Stream Deck. You can connect to the first available deck, query deck info, set or clear button configurations, create pages, switch pages, and more.

Troubleshooting

If you encounter issues, check these common scenarios: ensure the USB connection is active, verify that the Elgato software is not running, and confirm the MCP server is still running to receive button press callbacks.

# Example: re-connect to the Stream Deck after a disconnection
Connect to my Stream Deck

Notes on capabilities and examples

You can define the layout using natural language prompts that describe the desired pages and button actions. For example, you can instruct the AI to build a multi-page setup for podcasting, or a gaming profile with multiple integrations, and the server will apply the configuration across pages and buttons.

The server also supports Home Assistant integration, image icons for buttons, and state persistence across sessions.

Development and roadmaps

Development tasks include adding more integrations, improving icon generation, enabling button press webhooks, and supporting multiple decks.

Available tools

streamdeck_connect

Connect to the first available Stream Deck device to establish communication with the MCP server.

streamdeck_info

Retrieve information about the connected deck, including model, key count, and current page.

streamdeck_set_button

Configure a button's label, image, colors, and action to perform when pressed.

streamdeck_clear_button

Clear a single button's configuration.

streamdeck_set_brightness

Adjust the deck's brightness to a specified percentage.

streamdeck_create_page

Create a new button page profile and define its layout.

streamdeck_switch_page

Switch the active page on the Stream Deck.

streamdeck_list_pages

List all defined pages for the current deck.

streamdeck_delete_page

Delete a page except for the default main page.

streamdeck_disconnect

Cleanly disconnect the MCP server from the Stream Deck.