You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## Summary
- Rework the README into a centered, product-forward GitHub landing page
- Add a public GitHub user-attachments trailer embed
- Tighten install, feature, workflow, tools, and development sections
while preserving precise plugin-reuse language
## Tests
- git diff --check -- README.md
- Verified README local image path exists
- Verified trailer attachment with unauthenticated range GET: HTTP 206,
video/mp4
- Confirmed no tracked .mp4 or trailer/out artifacts
## Risk
- Docs-only change; no MCP server or Python behavior changed.
Stream Deck MCP lets agents build and reconfigure real Elgato Stream Deck profiles.
11
+
</p>
12
+
13
+
<palign="center">
14
+
<ahref="#quick-start">Quick Start</a>
15
+
·
16
+
<ahref="#demo">Demo</a>
17
+
·
18
+
<ahref="#features">Features</a>
19
+
·
20
+
<ahref="#tools">Tools</a>
21
+
·
22
+
<ahref="#development">Development</a>
23
+
</p>
24
+
25
+
Tell your AI what Stream Deck you want. Get back a polished profile with buttons, icons, colors, dials, touch-strip art, and the shell scripts behind it. Stream Deck MCP writes the same profile format the Elgato desktop app already uses, so agents can author real local decks without making you build a Stream Deck plugin first.
26
+
27
+
It works with Claude Desktop, Claude Code, Cursor, Codex, and any MCP client that can launch a stdio server.
28
+
29
+
## Quick Start
30
+
31
+
Claude Code:
32
+
33
+
```bash
34
+
claude mcp add streamdeck -- uvx streamdeck-mcp
35
+
```
36
+
37
+
Claude Desktop, Cursor, Codex, and other MCP clients can use the same command:
38
+
39
+
```json
40
+
{
41
+
"mcpServers": {
42
+
"streamdeck": {
43
+
"command": "uvx",
44
+
"args": ["streamdeck-mcp"]
45
+
}
46
+
}
47
+
}
48
+
```
6
49
7
-
streamdeck-mcp is the bridge: an MCP server that reads and writes Elgato Stream Deck profiles directly, in the format the desktop app already uses. Themed decks, per-project layouts, app-specific control boards — built in a single prompt instead of an hour in the GUI. Works with Claude Desktop, Claude Code, Cursor, Codex, and any MCP-compatible client.
50
+
Then ask your agent for a deck:
8
51
9
-
52
+
> Make me a Slack control board for my Stream Deck + XL.
10
53
11
-
> Asked Claude Desktop for *"a Slack control board"* — got back this profile. Buttons, icons, colors, and dials all authored in one shot via the MCP server.
54
+
For Claude Code, install the bundled designer skill for better layout, palette, hardware, and plugin-action guidance:
The decks aren't generic. When other MCP servers are loaded — Slack, Home Assistant, OBS, GitHub, Hue, the ones you already use — your AI queries them first to discover *your* channels, *your* devices, *your* scenes, then authors a deck around what's actually there. Icons render to match (~7,400 Material Design Icons bundled offline, or freeform text), so every button looks like it belongs. No Stream Deck SDK, no plugin authoring — just shell scripts and a prompt.
→ Queries your Slack MCP for channels, status, and unread state. Generates one channel-jump button per channel you actually use, status toggles (Active / Away / DND), a Read-All, and dials for unread counts. The screenshot above is one such result.
64
+
<palign="center">
65
+
<sub>Product trailer generated with Remotion, showing hardware inventory, plugin discovery, configured action reuse, and a final Stream Deck + XL reveal.</sub>
66
+
</p>
21
67
22
-
-***"A hello-kitty-themed Home Assistant dashboard for the living room."***
23
-
→ Pulls Home Assistant entities scoped to the living room area, then lays them out in pastel kawaii — scenes on row one, lights on row two, media on row three. Palette and icon style follow the theme.
68
+
## Features
24
69
25
-
-***"OBS control panel based on my actual scenes and audio inputs."***
26
-
→ Queries OBS for scenes, sources, and audio devices. Generates scene-switch buttons with the right transitions, source toggles, and dials for per-input gain on the touch strip.
70
+
-**Profile-native authoring** - reads and writes Elgato `ProfilesV3` files directly, with `ProfilesV2` fallback for older installs.
71
+
-**Hardware inventory** - discovers profile pages, device model names, key geometry, dials, and touch-strip support before writing.
72
+
-**Installed plugin discovery** - scans readable Stream Deck plugin manifests with `streamdeck_read_plugins` so agents can find plugin and action UUIDs.
73
+
-**Configured plugin action reuse** - reads existing buttons with `streamdeck_read_page` and preserves plugin-specific settings by copying `button.raw`; it does not infer private property-inspector settings.
74
+
-**Offline icon generation** - renders button and touch-strip PNGs from about 7,400 bundled Material Design Icons, or from short text labels.
75
+
-**Script-backed automations** - creates executable shell scripts in `~/StreamDeckScripts/` and wires them to Stream Deck Open actions.
76
+
-**Dial and touch-strip support** - installs a minimal bundled Stream Deck plugin when needed so encoder imagery survives app restarts.
77
+
-**Safe write cycle** - guards against the Elgato app overwriting manifest edits by enforcing a quit, write, relaunch workflow.
27
78
28
-
-***"A dev deck for this repo in Nordic colors."***
29
-
→ Reads your project's scripts (npm, Make, just — whatever's there), recent PRs via the GitHub MCP, and the local docs structure. Drops shell-script buttons for the most-used commands, PR/CI jumps, and a Nordic-palette icon set.
79
+
## Agentic Workflows
30
80
31
-
-***"A 'Friday demo' deck: open Zoom, mute Slack, set Hue to 'focus', start a screen recording."***
32
-
→ Composes across whatever MCPs you have loaded. Writes one shell script per action to `~/StreamDeckScripts/` and wires them to a single page with custom icons.
81
+
The point is not generic buttons. When your agent also has Slack, Home Assistant, OBS, GitHub, Hue, Spotify, or other MCP servers loaded, it can query those systems first and build around what is actually in your environment.
33
82
34
-
Same pattern every time: ask, your AI inventories your hardware and your other MCPs, plans the layout, generates icons, writes the profile files, restarts the Elgato app. Iteration is free — tweak the prompt, get a different deck.
83
+
Try prompts like:
35
84
36
-
## How it works
85
+
-**"Make me a control board for Slack."** Query channels, status, and unread state; create channel jumps, status toggles, read-all controls, and dials.
86
+
-**"A hello-kitty-themed Home Assistant dashboard for the living room."** Discover living-room entities, then lay out scenes, lights, and media controls in a matching visual style.
87
+
-**"OBS control panel based on my actual scenes and audio inputs."** Read scenes, sources, and devices; write scene switches, source toggles, and per-input dial controls.
88
+
-**"A dev deck for this repo in Nordic colors."** Read project scripts and GitHub context; create local command buttons, PR links, and CI shortcuts.
89
+
-**"A Friday demo deck."** Compose across Zoom, Slack, Hue, and screen recording by generating local scripts and wiring them to one page.
37
90
38
-
1.**Install the MCP server** in your AI client (snippets below).
39
-
2.**Install the designer skill** in Claude Code, or invoke the `design_streamdeck_deck` MCP prompt in any other client.
40
-
3.**Ask for a deck.** Your AI calls `streamdeck_read_profiles` to inventory the hardware, plans the layout, generates icons (~7,400 Material Design Icons bundled offline, or freeform text), writes the profile files, and restarts the Elgato app so the device picks up the changes.
91
+
Iteration is cheap: change the prompt, rerun the authoring flow, and get a new profile.
41
92
42
93
## Install
43
94
44
-
The packaged entrypoint is `streamdeck-mcp`, run via[`uvx`](https://docs.astral.sh/uv/). It edits the desktop app's `ProfilesV3` files when present and falls back to `ProfilesV2`.
95
+
The packaged entrypoint is `streamdeck-mcp`, run through[`uvx`](https://docs.astral.sh/uv/).
45
96
46
97
### Cursor
47
98
@@ -62,7 +113,7 @@ Or paste into `~/.cursor/mcp.json`:
62
113
63
114
### Claude Desktop
64
115
65
-
Paste into `~/Library/Application Support/Claude/claude_desktop_config.json`(macOS) or `%APPDATA%\Claude\claude_desktop_config.json`(Windows), then restart Claude Desktop:
116
+
Paste into `~/Library/Application Support/Claude/claude_desktop_config.json`on macOS or `%APPDATA%\Claude\claude_desktop_config.json`on Windows, then restart Claude Desktop:
66
117
67
118
```json
68
119
{
@@ -91,82 +142,71 @@ command = "uvx"
91
142
args = ["streamdeck-mcp"]
92
143
```
93
144
94
-
### Other MCP clients
95
-
96
-
Anything that speaks MCP over stdio works the same way — point it at `uvx streamdeck-mcp`. The JSON snippet above is the canonical shape.
97
-
98
-
### Note for Linux users
99
-
100
-
The default profile writer needs the Elgato Stream Deck desktop app, which is macOS- and Windows-only. On Linux, use the legacy USB-direct server instead — see [Legacy USB mode](#legacy-usb-mode) below.
145
+
### Other MCP Clients
101
146
102
-
## The `streamdeck-designer` skill
147
+
Anything that speaks MCP over stdio works the same way: point it at `uvx streamdeck-mcp`.
103
148
104
-
streamdeck-mcp ships with an **Agent Skill** that teaches Claude (in Claude Code) how to plan, theme, and author full decks end-to-end. The skill covers:
149
+
### Linux and Headless Setups
105
150
106
-
-**Hardware inventory** — always calls `streamdeck_read_profiles` first, then matches authoring style to your model.
-**Dials + touchstrip** — decision tree for + / + XL encoder layouts (`$X1` / `$A0` / …).
109
-
-**Integration recipes** — per-service patterns for Hue, OBS, Spotify, Home Assistant, Twitch, shell, browser. Credentials live in `~/StreamDeckScripts/.env`, never baked into scripts.
The default profile writer targets the Elgato Stream Deck desktop app, which is available on macOS and Windows. On Linux, headless machines, or setups where you want the MCP server to own the hardware directly, use the legacy USB server:
The skill is copied to `~/.claude/skills/streamdeck-designer/`. Restart Claude Code (or start a new session) and it auto-loads when your request matches a deck-design intent. Re-run with `--force` to upgrade after a version bump.
119
-
120
-
### Other MCP clients
157
+
Client config shape:
121
158
122
-
Clients that don't load Claude Code skills (Claude Desktop, Cursor, Codex, …) get a condensed mirror via the **`design_streamdeck_deck`** MCP prompt. Most clients expose it as a slash command or prompt picker — invoke it before describing the deck you want, and pass the user's intent via the `intent` argument if your client supports it.
|`streamdeck_read_profiles`| Lists desktop profiles and page directories from the active ProfilesV3 or ProfilesV2 store |
129
-
|`streamdeck_read_page`| Reads a page manifest and returns simplified button details plus the raw manifest |
130
-
|`streamdeck_write_page`| Creates a new page or rewrites an existing page manifest |
131
-
|`streamdeck_create_icon`| Generates a PNG icon from a Material Design Icons name (e.g. `mdi:cpu-64-bit`) or from text — provide one or the other, not both. `shape="button"` (72×72, default) for keypad keys and dial faces; `shape="touchstrip"` (200×100) for + / + XL touch strip backgrounds. ~7,400 MDI icons are bundled offline; unknown names return close-match suggestions |
132
-
|`streamdeck_create_action`| Creates an executable shell script in `~/StreamDeckScripts/` and returns an Open action block |
133
-
|`streamdeck_restart_app`| Restarts the Stream Deck desktop app after profile changes (macOS only — raises on other platforms) |
134
-
|`streamdeck_install_mcp_plugin`| Installs the bundled streamdeck-mcp Stream Deck plugin into the Elgato Plugins directory. `streamdeck_write_page` auto-installs it the first time an encoder needs it, so direct use is rarely required |
174
+
|`streamdeck_read_plugins`| Lists installed Stream Deck plugins and declared actions from readable plugin manifests. Protected or binary manifests are reported with diagnostics instead of failing the whole catalog. |
175
+
|`streamdeck_read_profiles`| Lists desktop profiles, device metadata, page directories, and active profile roots from `ProfilesV3` or `ProfilesV2`. |
176
+
|`streamdeck_read_page`| Reads a page manifest and returns simplified button details plus raw native action objects. |
177
+
|`streamdeck_write_page`| Creates or rewrites a page manifest. Use copied `button.raw` values when reusing configured third-party plugin actions. |
178
+
|`streamdeck_create_icon`| Generates button or touch-strip PNGs from Material Design Icons or text. Icons are bundled offline; unknown names return close-match suggestions. |
179
+
|`streamdeck_create_action`| Creates an executable shell script in `~/StreamDeckScripts/` and returns an Open action block. |
180
+
|`streamdeck_restart_app`| Restarts the macOS Stream Deck desktop app after profile changes. |
181
+
|`streamdeck_install_mcp_plugin`| Installs the bundled streamdeck-mcp Stream Deck plugin used for durable encoder imagery. Usually auto-installed by `streamdeck_write_page`. |
135
182
136
-
## Editing workflow
183
+
Prompt support:
137
184
138
-
The Elgato desktop app keeps every profile in memory and rewrites the on-disk manifests from that snapshot when it quits — so any edit made while the app is running is wiped the next time it closes. The profile writer enforces a quit → write → relaunch cycle:
185
+
| Prompt | What it does |
186
+
|--------|---------------|
187
+
|`design_streamdeck_deck`| Gives non-skill-aware MCP clients a condensed deck-design briefing before the user describes the deck they want. |
139
188
140
-
1. Ensure the Elgato app is not running, or pass `auto_quit_app: true` to `streamdeck_write_page` to have it quit the app for you (AppleScript first, `killall` fallback).
141
-
2. Make as many `streamdeck_write_page` calls as you need — the app stays quit between them.
142
-
3. Call `streamdeck_restart_app` when you're done. The device re-reads the manifests on launch and your changes appear.
189
+
## streamdeck-designer Skill
143
190
144
-
`streamdeck_write_page` raises `StreamDeckAppRunningError` when the app is running and `auto_quit_app` isn't set, so you can't accidentally write changes that get silently discarded.
191
+
Stream Deck MCP ships with an Agent Skill for Claude Code that teaches the agent how to plan, theme, and author full decks end to end.
145
192
146
-
**Platform support.** The running-app guard, `auto_quit_app`, and `streamdeck_restart_app` are macOS-only. On Windows the Elgato app still clobbers manifests on close, so you'll need to quit it manually before authoring and relaunch it after — `auto_quit_app: true` is silently a no-op on non-macOS, and `streamdeck_restart_app` errors.
193
+
Install it with:
147
194
148
-
If your Elgato app lives somewhere other than `/Applications/Elgato Stream Deck.app`, set `STREAMDECK_APP_PATH` to the bundle path.
149
-
150
-
## Under the hood
151
-
152
-
-**`ProfilesV3` is preferred** when present (page UUIDs map cleanly to directories). `ProfilesV2` is still supported, but existing pages should be targeted by `directory_id` or `page_index` because Elgato uses opaque directory names there.
153
-
-**Native action objects** are accepted directly by `streamdeck_write_page`, alongside convenience fields like `path`, `action_type`, `plugin_uuid`, and `action_uuid`.
154
-
-**Generated icons** live in `~/.streamdeck-mcp/generated-icons/`. **Generated shell scripts** live in `~/StreamDeckScripts/`.
155
-
-**The bundled streamdeck-mcp plugin** is installed into the Stream Deck Plugins directory (e.g., `~/Library/Application Support/com.elgato.StreamDeck/Plugins/` on macOS, `%APPDATA%\Elgato\StreamDeck\Plugins\` on Windows). It's a minimal shell whose only job is to declare encoder support so per-instance `Encoder.Icon` / `Encoder.background` writes survive an Elgato app restart.
The skill is copied to `~/.claude/skills/streamdeck-designer/`. Restart Claude Code or start a new session after installing it. Re-run with `--force` to upgrade after a package update.
158
200
159
-
The original USB-direct server is preserved for backwards compatibility — useful when you'd rather have the MCP server own the hardware directly (Linux, headless setups, or environments where the Elgato app isn't running). It exposes a different tool surface focused on direct hardware control:
- Hardware inventory and model-specific layout planning.
204
+
- Theme palettes, typography strategy, and icon-color guidance.
205
+
- Dial and touch-strip authoring for Stream Deck + and + XL devices.
206
+
- Integration recipes for Hue, OBS, Spotify, Home Assistant, Twitch, shell commands, and browser workflows.
207
+
- Existing plugin action reuse through `streamdeck_read_page` and `button.raw`.
162
208
163
-
Run via:
164
-
165
-
```bash
166
-
uvx --from streamdeck-mcp streamdeck-mcp-usb
167
-
```
168
-
169
-
In a client config, keep `"command": "uvx"` and use `"args": ["--from", "streamdeck-mcp", "streamdeck-mcp-usb"]`.
209
+
Clients that do not load Claude Code skills can invoke the `design_streamdeck_deck` MCP prompt instead.
170
210
171
211
## Development
172
212
@@ -184,13 +224,29 @@ To audit this repo against the shared Very Good Plugins MCP standards:
184
224
../mcp-ecosystem/scripts/audit-server.sh .
185
225
```
186
226
187
-
## Support
227
+
### Authoring Notes
228
+
229
+
-`ProfilesV3` is preferred when present. `ProfilesV2` is still supported, but existing pages should be targeted by `directory_id` or `page_index` because Elgato uses opaque directory names there.
230
+
- The Elgato desktop app keeps profiles in memory and can overwrite on-disk manifest edits when it quits. `streamdeck_write_page` raises `StreamDeckAppRunningError` when the app is running and `auto_quit_app` is not set.
231
+
- On macOS, pass `auto_quit_app: true` to quit the app before writing, then call `streamdeck_restart_app` when done. On Windows, quit and relaunch the Elgato app manually.
232
+
- Set `STREAMDECK_APP_PATH` if your Elgato app is not installed at `/Applications/Elgato Stream Deck.app`.
233
+
- Generated icons live in `~/.streamdeck-mcp/generated-icons/`. Generated shell scripts live in `~/StreamDeckScripts/`.
234
+
235
+
### Legacy USB Mode
236
+
237
+
The original USB-direct server is preserved for backwards compatibility. It exposes direct hardware tools:
0 commit comments