Streamdeck MCP

🚀 Stream Deck MCP · v0.1.0

🎛️ Let AI design your Stream Deck setup. Describe what you want in plain English, and your AI will build it for you. This tool simplifies the often-tedious process of configuring your Stream Deck, making it a breeze to set up for various tasks.

🚀 Quick Start

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

Installation

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

Add to Claude Desktop

Edit ~/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"
      ]
    }
  }
}

Usage

In Claude:

Connect to my Stream Deck

Then:

Set button 0 to "Lights" with a blue background
Set button 1 to "Music" with action "open -a Spotify"
Create a page called "gaming" and switch to it

✨ Features

The Problem

Stream Deck is a powerful tool, but configuring it can be extremely tedious. Navigating through the GUI, searching for icons, and setting up multi - page workflows can take a significant amount of time.

The Solution

Simply tell your AI what you need. For example:

"Design a podcast studio layout with pages for recording, editing, and publishing.
Include buttons for mic mute, recording start/stop, sound effects, and scene switching."

The AI will then design the strategy, create the pages, and configure every button for you.

What You Can Do

• 🎙️ "Set up my Stream Deck for podcasting": The AI will design a multi - page system.
• 🏠 "Create a home automation page": Generate buttons for lights, scenes, and climate control.
• 🎮 "Build a gaming profile with Discord, OBS, and Spotify": With just one prompt, get a full setup.
• 🔄 "Redesign my layout to be more intuitive": The AI understands your workflow and suggests improvements.

This tool is compatible with Stream Deck, Stream Deck Mini, Stream Deck XL, Stream Deck MK.2, and Stream Deck +.

📦 Installation

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

Installation Steps

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

💻 Usage Examples

Basic Usage

In Claude, you can use the following commands:

Connect to my Stream Deck

Set button 0 to "Lights" with a blue background

Advanced Usage

"Design a podcast studio layout with pages for recording, editing, and publishing.
Include buttons for mic mute, recording start/stop, sound effects, and scene switching."

📚 Documentation

Available Tools

Natural Language Examples

You can simply tell Claude what you want, such as:

• "Connect to my Stream Deck and show me the layout"
• "Set button 0 to say 'Lights' with a blue background"
• "Make button 4 open Spotify when I press it"
• "Create a 'gaming' page with Discord, Steam, and OBS buttons"
• "Switch to the gaming page"
• "Set brightness to 50%"

Button Layout

Buttons are numbered left - to - right, top - to - bottom: Stream Deck (15 keys, 5×3):

[0]  [1]  [2]  [3]  [4]
[5]  [6]  [7]  [8]  [9]
[10] [11] [12] [13] [14]

Stream Deck Mini (6 keys, 3×2):

[0]  [1]  [2]
[3]  [4]  [5]

Stream Deck XL (32 keys, 8×4):

[0]  [1]  [2]  [3]  [4]  [5]  [6]  [7]
[8]  [9]  [10] [11] [12] [13] [14] [15]
[16] [17] [18] [19] [20] [21] [22] [23]
[24] [25] [26] [27] [28] [29] [30] [31]

Home Assistant Integration

You can wire buttons to your HA entities. For example:

Set up my Stream Deck for home control:
- Button 0: "Office Lights" that toggles light.office_ceiling
- Button 1: "All Off" that runs a scene
- Button 4: Page switch to "media" page

The action field accepts any shell command. You can use curl to hit HA webhooks or the HA CLI.

Custom Icons

You can drop PNG/JPG files anywhere and reference them. For example:

Set button 5 with image ~/icons/spotify.png

Images will be auto - scaled to the button size (72×72 or 96×96 depending on the deck model).

State Storage

Configs are persisted at ~/.streamdeck-mcp/:

• pages.json: Button appearances per page
• buttons.json: Button actions per page

🔧 Technical Details

Troubleshooting

⚠️ Important Note

• "No Stream Deck found": Check the USB connection. On Linux, make sure you added the udev rule and reloaded it. On macOS, grant the terminal USB access in System Preferences → Security & Privacy.
• "streamdeck library not installed": Run uv pip install streamdeck pillow.
• Buttons don't respond to presses: Physical button callbacks require the MCP server to stay running. The server runs while Claude Desktop is open.
• "Deck disconnected" errors: The server handles USB disconnections gracefully. Just say "Connect to my Stream Deck" again to reconnect.

Development

# Setup
uv venv && uv pip install -e ".[dev]"

# Run server
uv run server.py

# Run tests (no hardware required)
uv run pytest tests/ -v

# Lint
uv run ruff check .

Roadmap

• [ ] Home Assistant entity browser integration
• [ ] Icon generation from emoji
• [ ] Button press webhooks
• [ ] Multi - deck support

📄 License

This project is licensed under the MIT License. Because hardware control should be free.

Built by Jack Arturo at Very Good Plugins 🧡