Skip to main content
Glama

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.

It works with Claude Desktop, Claude Code, Cursor, Codex, and any MCP client that can launch a stdio server.

Quick Start

Claude Code:

claude mcp add streamdeck -- uvx streamdeck-mcp

Claude Desktop, Cursor, Codex, and other MCP clients can use the same command:

{
  "mcpServers": {
    "streamdeck": {
      "command": "uvx",
      "args": ["streamdeck-mcp"]
    }
  }
}

Then ask your agent for a deck:

Make me a Slack control board for my Stream Deck + XL.

For Claude Code, install the bundled designer skill for better layout, palette, hardware, and plugin-action guidance:

uvx --from streamdeck-mcp streamdeck-mcp-install-skill

Related MCP server: streamdeck-mcp

Demo

Features

  • Profile-native authoring - reads and writes Elgato ProfilesV3 files directly, with ProfilesV2 fallback for older installs.

  • Hardware inventory - discovers profile pages, device model names, key geometry, dials, and touch-strip support before writing.

  • Configured action search - streamdeck_find_actions scans existing profiles/pages for paste-ready plugin buttons and dials (including protected first-party Elgato plugins configured in the app).

  • Installed plugin discovery - scans readable Stream Deck plugin manifests with streamdeck_read_plugins so agents can find plugin and action UUIDs when synthesizing new actions.

  • Configured plugin action reuse - prefers copying existing actions via find_actions or streamdeck_read_page's button.raw so private Property Inspector settings stay intact.

  • Offline icon generation - renders button and touch-strip PNGs from about 7,400 bundled Material Design Icons, or from short text labels.

  • Script-backed automations - creates executable shell scripts in ~/StreamDeckScripts/ and wires them to Stream Deck Open actions when no plugin action fits.

  • Dial and touch-strip support - installs a minimal bundled Stream Deck plugin when needed so encoder imagery survives app restarts.

  • Safe write cycle - guards against the Elgato app overwriting manifest edits by enforcing a quit, write, relaunch workflow.

Agentic Workflows

The point is not generic buttons. Prefer reusing actions the user already configured in the Stream Deck app (Hue, OBS, Home Assistant, Spotify plugins, etc.), then compose them onto a themed page. When your agent also has Slack, Home Assistant, OBS, GitHub, Hue, Spotify, or other MCP servers loaded, it can query those systems to pick the right entities — and still wire the deck through native plugin actions when available, falling back to scripts only when needed.

Try prompts like:

  • "Make me a control board for Slack." Query channels, status, and unread state; create channel jumps, status toggles, read-all controls, and dials.

  • "A hello-kitty-themed Home Assistant dashboard for the living room." Find existing HA plugin buttons with streamdeck_find_actions, then lay them out with a matching visual style — or discover living-room entities via MCP and synthesize/scripts when nothing is configured yet.

  • "OBS control panel based on my actual scenes and audio inputs." Reuse configured OBS plugin actions when present; otherwise read scenes/sources and write scene switches, source toggles, and per-input dial controls.

  • "A dev deck for this repo in Nordic colors." Read project scripts and GitHub context; create local command buttons, PR links, and CI shortcuts.

  • "A Friday demo deck." Compose across Zoom, Slack, Hue, and screen recording by finding configured plugin actions first, then generating local scripts for the gaps.

Iteration is cheap: change the prompt, rerun the authoring flow, and get a new profile.

Install

The packaged entrypoint is streamdeck-mcp, run through uvx.

Cursor

Install MCP Server

Or paste into ~/.cursor/mcp.json:

{
  "mcpServers": {
    "streamdeck": {
      "command": "uvx",
      "args": ["streamdeck-mcp"]
    }
  }
}

Claude Desktop

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:

{
  "mcpServers": {
    "streamdeck": {
      "command": "uvx",
      "args": ["streamdeck-mcp"]
    }
  }
}

Claude Code

claude mcp add streamdeck -- uvx streamdeck-mcp

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.streamdeck]
command = "uvx"
args = ["streamdeck-mcp"]

Other MCP Clients

Anything that speaks MCP over stdio works the same way: point it at uvx streamdeck-mcp.

Linux and Headless Setups

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:

uvx --from streamdeck-mcp streamdeck-mcp-usb

Client config shape:

{
  "mcpServers": {
    "streamdeck": {
      "command": "uvx",
      "args": ["--from", "streamdeck-mcp", "streamdeck-mcp-usb"]
    }
  }
}

Tools

Tool

What it does

streamdeck_find_actions

Searches configured buttons/dials across profiles and returns paste-ready native action objects for streamdeck_write_page.

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.

streamdeck_read_profiles

Lists desktop profiles, device metadata, page directories, and active profile roots from ProfilesV3 or ProfilesV2.

streamdeck_read_page

Reads a page manifest and returns simplified button details plus raw native action objects.

streamdeck_write_page

Creates or rewrites a page manifest. Prefer action from find_actions / button.raw when reusing configured third-party plugin actions.

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.

streamdeck_create_action

Creates an executable shell script in ~/StreamDeckScripts/ and returns an Open action block.

streamdeck_restart_app

Restarts the macOS Stream Deck desktop app after profile changes.

streamdeck_install_mcp_plugin

Installs the bundled streamdeck-mcp Stream Deck plugin used for durable encoder imagery. Usually auto-installed by streamdeck_write_page.

Prompt support:

Prompt

What it does

design_streamdeck_deck

Gives non-skill-aware MCP clients a condensed deck-design briefing before the user describes the deck they want.

streamdeck-designer Skill

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.

Install it with:

uvx --from streamdeck-mcp streamdeck-mcp-install-skill

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.

The skill covers:

  • Hardware inventory and model-specific layout planning.

  • Theme palettes, typography strategy, and icon-color guidance.

  • Dial and touch-strip authoring for Stream Deck + and + XL devices.

  • Integration recipes for Hue, OBS, Spotify, Home Assistant, Twitch, shell commands, and browser workflows.

  • Existing plugin action reuse through streamdeck_find_actions and streamdeck_read_page / button.raw.

Clients that do not load Claude Code skills can invoke the design_streamdeck_deck MCP prompt instead.

Development

git clone https://github.com/verygoodplugins/streamdeck-mcp.git
cd streamdeck-mcp
uv venv && uv pip install -e ".[dev]"
uv run pytest tests/ -v
uv run ruff check .

To audit this repo against the shared Very Good Plugins MCP standards:

../mcp-ecosystem/scripts/audit-server.sh .

Authoring Notes

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

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

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

  • Set STREAMDECK_APP_PATH if your Elgato app is not installed at /Applications/Elgato Stream Deck.app.

  • Generated icons live in ~/.streamdeck-mcp/generated-icons/. Generated shell scripts live in ~/StreamDeckScripts/.

Legacy USB Mode

The original USB-direct server is preserved for backwards compatibility. It exposes direct hardware tools:

streamdeck_list_devices, streamdeck_connect, streamdeck_info, streamdeck_set_button, streamdeck_set_buttons, streamdeck_clear_button, streamdeck_get_button, streamdeck_clear_all, streamdeck_set_brightness, streamdeck_create_page, streamdeck_switch_page, streamdeck_list_pages, streamdeck_delete_page, streamdeck_disconnect.

When multiple decks are attached, call streamdeck_list_devices first, then pass the desired serial to streamdeck_connect. Omitting serial preserves the legacy behavior of opening the first enumerated deck.

Run it with:

uvx --from streamdeck-mcp streamdeck-mcp-usb

Support

Built by Very Good Plugins.

Available Tools

7 tools
streamdeck_create_actionA

Create an executable shell script in ~/StreamDeckScripts and return a native Open action block for it.

Inputs: name (required), command (required), working_directory, filename.

streamdeck_create_iconA

Generate one or many PNG icons. Button icons are 72x72 px; touchstrip segment icons are 200x100 px (use shape='touchstrip'). For a single icon: pass 'icon' (a Material Design Icons name like 'mdi:cpu-64-bit') OR 'text' (mutually exclusive with 'icon' — titles go on streamdeck_write_page's 'title' field since Elgato overlays them on images). For a full deck (often 30+ icons): pass 'icons' as a list of spec dicts to generate them all in one call and avoid the round-trip timeouts serial calls hit. ~7400 MDI icons bundled offline; unknown names return close-match suggestions. Returns either a single {path, size, ...} dict or {"icons": [...]} when 'icons' is used (each list element is a per-icon result or an {"error"} entry for that spec).

Inputs: icon, icon_color, icon_scale, shape, +7 more.

streamdeck_install_mcp_pluginA

Install the bundled streamdeck-mcp Stream Deck plugin into the user's Elgato Plugins directory. The plugin is a minimal shell that declares encoder support so that per-instance touchstrip icons and backgrounds written by streamdeck_write_page survive an Elgato app restart. Idempotent — returns installed=false when already present unless force=true. streamdeck_write_page also auto-installs this plugin when an encoder button targets it, so most callers do not need to invoke this directly.

Inputs: force.

streamdeck_read_pageA

Read a profile page by profile name or ID and page index or directory ID.

Inputs: profile_name, profile_id, page_index, directory_id.

streamdeck_read_profilesB

List Stream Deck desktop profiles from the active ProfilesV3 or ProfilesV2 directory.

Inputs: no named parameters.

streamdeck_restart_appA

Restart the macOS Stream Deck desktop app after profile changes.

Inputs: no named parameters.

streamdeck_write_pageA

Create a new page or replace/update an existing Stream Deck desktop page manifest. IMPORTANT: the Elgato desktop app overwrites profile manifests from its in-memory state on quit, so writes made while the app is running are lost. This tool refuses to write when the app is running unless auto_quit_app=True is passed. Call streamdeck_restart_app once your edits are complete to make the changes visible on the device.

Inputs: profile_name, profile_id, page_index, directory_id, +6 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: creating actions, creating icons, installing the plugin, reading/writing pages, reading profiles, and restarting the app. Overlap is minimal to none.

    Naming Consistency5/5

    All tools follow a consistent 'streamdeck_verb_noun' pattern (e.g., create_action, read_page, restart_app). The naming is predictable and uniform.

    Tool Count5/5

    With 7 tools, the server is well-scoped for the domain of Stream Deck profile management, covering essential operations without excess or omission.

    Completeness4/5

    The tool set covers core workflows (creating icons, actions, pages, profiles) but lacks delete operations for pages or actions, which is a minor gap.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP-capable AI agents such as Claude, Codex, Gemini CLI, Cursor and Zed to design and manage a Stream Deck by reading layouts, building pages and keys, setting icons and wallpapers, managing profiles and taking screenshots to verify their own work. Access is governed by read-only, edit-layout and full-control levels, with approval prompts before any tool runs something on the user's computer.
      MIT