streamdeck

This MCP server automates the configuration and control of Elgato Stream Deck devices via Claude and a Python-based MCP server. It exposes a suite of tools that let you connect to a Stream Deck, query deck details, set button text/images/colors and actions, create and switch pages, and manage multiple pages or decks. You can use natural language prompts to craft complex button layouts, multi-page profiles, and integrations with other apps or services. The available tools include: streamdeck_connect to connect to the first available deck, streamdeck_info to retrieve model and page data, streamdeck_set_button to configure a button’s appearance and action, streamdeck_clear_button to remove button content, streamdeck_set_brightness to adjust brightness, streamdeck_create_page to add a new page, streamdeck_switch_page to change the active page, streamdeck_list_pages to enumerate pages, streamdeck_delete_page to remove a page (except the main one), and streamdeck_disconnect to cleanly disconnect. You can describe your desired layout to Claude, and it will translate that into page creation, button assignments, and the necessary actions.

Prerequisites:

• Python 3.8+ installed on your system
• Git installed
• Access to a Python environment where you can install local packages

Install and run the MCP server:

1. Clone the repository: git clone https://github.com/verygoodplugins/streamdeck-mcp.git
2. Change into the project directory: cd streamdeck-mcp
3. Create and activate a Python virtual environment using uv: uv venv
4. Install the MCP package in editable mode: uv pip install -e .
5. Run the server (from the project directory): uv run server.py

Configuration via MCP config (example):

• The following MCP config uses uv to run the server from a directory. Adjust the path to where you cloned the repo:

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

Tips and notes:

• Ensure exclusive USB access as the Stream Deck software must not be running while the MCP server is controlling the device.
• If you encounter permission issues on Linux for non-root access, consider adding a udev rule as described in the README to grant access to the USB device.
• The button actions can be shell commands, or integrations with other apps (e.g., open a URL, launch an application, etc.). You can persist page configurations under the project in Claude or any provided state storage used by the MCP.
• Development and testing can run without hardware using the provided test commands; use the provided development steps to install dev dependencies and run tests.
• If you move the project directory, update the MCP config to reflect the new --directory path.