🎛️ Stream Deck MCP · v0.1.0

Let AI design your Stream Deck setup — Describe what you want in plain English. Your AI builds it.

The Problem

Stream Deck is powerful, but configuring it is tedious. Clicking through the GUI, finding icons, setting up multi-page workflows — it takes forever.

The Solution

Tell your AI what you want:

"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."

Your AI designs the strategy, creates the pages, and configures every button. Done.

✨ What You Can Do

🎙️ "Set up my Stream Deck for podcasting" — AI designs a multi-page system 🏠 "Create a home automation page" — Buttons for lights, scenes, climate 🎮 "Build a gaming profile with Discord, OBS, and Spotify" — One prompt, full setup 🔄 "Redesign my layout to be more intuitive" — AI understands workflow, suggests improvements

Works with: Stream Deck, Stream Deck Mini, Stream Deck XL, Stream Deck MK.2, Stream Deck +

⚠️ Important: Quit Elgato Software First

This MCP server requires exclusive USB access. You must quit the Elgato Stream Deck software before using it:

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

The Stream Deck can only be controlled by one application at a time. While using this MCP server, the Elgato software cannot run (and vice versa).

🏃 Quick Start — 2 Minutes to Buttons

1️⃣ 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

2️⃣ Install

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

3️⃣ 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"
      ]
    }
  }
}

4️⃣ Use It

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

That's it! 🎉

🛠️ Available Tools

Tool	What it does
`streamdeck_connect`	Connect to first available deck
`streamdeck_info`	Get deck model, key count, current page
`streamdeck_set_button`	Set text, image, colors, and action
`streamdeck_clear_button`	Clear a single button
`streamdeck_set_brightness`	0-100% brightness
`streamdeck_create_page`	Create a new button profile
`streamdeck_switch_page`	Switch active page
`streamdeck_list_pages`	List all pages
`streamdeck_delete_page`	Delete a page (except "main")
`streamdeck_disconnect`	Clean disconnect

Natural Language Examples

Just tell Claude what you want:

"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

Wire buttons to your HA entities. Example prompt:

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 — use curl to hit HA webhooks or the HA CLI.

🎨 Custom Icons

Drop PNG/JPG files anywhere and reference them:

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

Images auto-scale to button size (72×72 or 96×96 depending on deck model).

📁 State Storage

Configs persist at ~/.streamdeck-mcp/:

pages.json — Button appearances per page
buttons.json — Button actions per page

⚠️ Troubleshooting

"No Stream Deck found"

Check USB connection
On Linux: Did you add the udev rule and reload?
On macOS: Grant terminal USB access in System Preferences → Security & Privacy

"streamdeck library not installed"

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

MIT — Because hardware control should be free.

Built by Jack Arturo at Very Good Plugins 🧡

streamdeck-mcp

Documentation