https://github.com/verygoodplugins/streamdeck-mcp
MCP server for Elgato Stream Deck control — set buttons, manage pages, wire actions
https://github.com/verygoodplugins/streamdeck-mcp
elgato home-automation mcp mcp-server modelcontextprotocol streamdeck
Last synced: 5 days ago
JSON representation
MCP server for Elgato Stream Deck control — set buttons, manage pages, wire actions
- Host: GitHub
- URL: https://github.com/verygoodplugins/streamdeck-mcp
- Owner: verygoodplugins
- License: mit
- Created: 2025-12-24T21:52:03.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-12-25T07:40:14.000Z (about 1 month ago)
- Last Synced: 2025-12-26T17:03:59.028Z (about 1 month ago)
- Topics: elgato, home-automation, mcp, mcp-server, modelcontextprotocol, streamdeck
- Language: Python
- Size: 87.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 🎛️ Stream Deck MCP · v0.1.0
> **Let AI design your Stream Deck setup** — Describe what you want in plain English. Your AI builds it.
[](LICENSE)
## 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:
```bash
# 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
```bash
# 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
```bash
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):
```json
{
"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"**
```bash
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
```bash
# 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](https://verygoodplugins.com/?utm_source=github) at Very Good Plugins* 🧡
[](https://x.com/jjack_arturo)