Stream Deck MCP lets AI agents programmatically build, reconfigure, and manage Elgato Stream Deck profiles — including buttons, icons, dials, touch strips, and shell script automations — without manual use of the Elgato desktop app.
Core capabilities:
Discover hardware & plugins (streamdeck_read_plugins): Scan installed Stream Deck plugins, their UUIDs, and declared actions. Identify connected devices, key layouts, dials, and touch-strip support.
Read profiles (streamdeck_read_profiles): List existing desktop profiles, device metadata, page directories, and active roots (supports ProfilesV3 and ProfilesV2).
Read page contents (streamdeck_read_page): Inspect a profile page to get button details and raw native action objects, enabling reuse of configured third-party plugin actions.
Write/create pages (streamdeck_write_page): Create or overwrite pages with fully configured buttons — titles, icons, actions, dial/encoder layouts, and touch-strip backgrounds. Safely handles the app's in-memory state via a quit-write-relaunch cycle.
Generate icons (streamdeck_create_icon): Render button (72×72 px) or touch-strip (200×100 px) PNGs offline from ~7,400 bundled Material Design Icons or text labels, with control over color, scale, background, and shape. Supports batch generation in a single call.
Create shell script actions (streamdeck_create_action): Write executable shell scripts to ~/StreamDeckScripts/ and return a native Stream Deck Open action block wiring a button press to that script.
Restart the desktop app (streamdeck_restart_app): Restart the macOS Stream Deck app after profile changes so edits appear on the device.
Install the bundled plugin (streamdeck_install_mcp_plugin): Install a minimal plugin enabling durable encoder/dial touch-strip imagery across app restarts (usually auto-invoked by streamdeck_write_page).
Legacy USB mode: For Linux/headless setups, a legacy USB server provides direct hardware control — setting buttons, adjusting brightness, and managing pages on the device.
Agentic workflow prompt (Claude Code): The design_streamdeck_deck prompt guides agents through hardware inventory, theme planning, and end-to-end deck authoring.
Allows creating a dev deck with recent PRs, CI status, and shell scripts for common commands.
Allows creating a themed dashboard for controlling Home Assistant entities (scenes, lights, media) scoped to specific areas.
Allows creating a control board with channel-jump buttons, status toggles (Active/Away/DND), unread counts, and dials for unread counts.
Allows creating a music control deck with playback actions (play, pause, skip, volume) and themed icon sets.
Allows creating a streamer control deck with scene switching, alerts, and chat actions.
Allows creating a deck with actions to open Zoom, mute/unmute, and start screen recordings.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@streamdeck-mcp Make me a Slack control board with my channels"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Claude Code:
claude mcp add streamdeck -- uvx streamdeck-mcpClaude 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-skillRelated MCP server: Elgato MCP Server
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.
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.
The packaged entrypoint is streamdeck-mcp, run through uvx.
Or paste into ~/.cursor/mcp.json:
{
"mcpServers": {
"streamdeck": {
"command": "uvx",
"args": ["streamdeck-mcp"]
}
}
}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 mcp add streamdeck -- uvx streamdeck-mcpAdd to ~/.codex/config.toml:
[mcp_servers.streamdeck]
command = "uvx"
args = ["streamdeck-mcp"]Anything that speaks MCP over stdio works the same way: point it at uvx streamdeck-mcp.
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-usbClient config shape:
{
"mcpServers": {
"streamdeck": {
"command": "uvx",
"args": ["--from", "streamdeck-mcp", "streamdeck-mcp-usb"]
}
}
}Tool | What it does |
| Searches configured buttons/dials across profiles and returns paste-ready native |
| 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. |
| Lists desktop profiles, device metadata, page directories, and active profile roots from |
| Reads a page manifest and returns simplified button details plus raw native action objects. |
| Creates or rewrites a page manifest. Prefer |
| Generates button or touch-strip PNGs from Material Design Icons or text. Icons are bundled offline; unknown names return close-match suggestions. |
| Creates an executable shell script in |
| Restarts the macOS Stream Deck desktop app after profile changes. |
| Installs the bundled streamdeck-mcp Stream Deck plugin used for durable encoder imagery. Usually auto-installed by |
Prompt support:
Prompt | What it does |
| Gives non-skill-aware MCP clients a condensed deck-design briefing before the user describes the deck they want. |
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-skillThe 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.
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 .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/.
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-usbBuilt by Very Good Plugins.
Create an executable shell script in ~/StreamDeckScripts and return a native Open action block for it.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Human-readable action name used for the script filename and button label. | |
| command | Yes | Shell command to run when the button is pressed. | |
| working_directory | No | Optional working directory to cd into before executing the command. | |
| filename | No | Optional override for the script filename. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full behavioral transparency. It mentions file creation and return value but omits details like overwrite behavior, permission requirements, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that conveys the essential information without any redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides basic functionality but lacks details on return value format, prerequisites, or error scenarios. Given missing annotations and no output schema, more context would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining that 'name' is used for both filename and button label, which is not in the schema. However, it does not mention the optional parameters like 'filename' and 'working_directory'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates an executable shell script in ~/StreamDeckScripts and returns a native Open action block. It distinguishes from siblings like streamdeck_create_icon and streamdeck_read_page by specifying the exact output and location.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating action buttons with shell commands, but lacks explicit guidance on when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| icon | No | Material Design Icons name, e.g. 'mdi:cpu-64-bit', 'mdi:volume-high', 'mdi:microphone'. The 'mdi:' prefix is optional. Aliases are honored. | |
| icon_color | No | Hex color for the icon glyph, e.g. '#00ff88'. Defaults to text_color. | |
| icon_scale | No | Fraction of the canvas the glyph bounding box fills (0.1-1.0). Defaults to 1.0 — edge-to-edge, matching how Elgato's own icons fill the touchstrip slot. Reduce to ~0.75-0.85 for keypad buttons that also have a bottom title so the glyph doesn't touch the label. | |
| shape | No | Output canvas. 'button' (default) is 72x72 — keypad keys and encoder dial faces. 'touchstrip' is 200x100 — per-segment background above a Stream Deck + / + XL dial; pair with a button's strip_background_path on streamdeck_write_page. | |
| transparent_bg | No | Generate an RGBA PNG with a transparent canvas instead of filling with bg_color. Use this for dial Icons that overlay a touchstrip background so the glyph composes naturally. Leave false (default) for keypad faces and touchstrip backgrounds. | |
| text | No | Text for a centered text-only icon. Mutually exclusive with 'icon'. For icon buttons that need a label, use the button's 'title' field on streamdeck_write_page. | |
| bg_color | No | ||
| text_color | No | ||
| font_size | No | ||
| filename | No | ||
| icons | No | Batch generation: a list of icon spec objects, each carrying the same fields as a single-icon call (icon/text/icon_color/bg_color/icon_scale/shape/transparent_bg/text_color/font_size/filename). When this field is present, all other single-icon fields at the top level are ignored and the response shape becomes {"icons": [per-spec result]}. Use this for 30+ icon decks to avoid per-call round-trip cost. Accepts either a JSON array or a JSON-encoded string containing an array — some MCP clients stringify nested arrays in transit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses return shapes (single dict or array), behavior for unknown MDI names (close-match suggestions), that batch 'icons' ignores other top-level fields, and that some MCP clients stringify nested arrays. This level of detail is comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with a clear summary first, then breakdown of single vs batch, then additional details. Though slightly lengthy, every sentence provides useful context. Front-loaded with the most critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 11 parameters and no output schema, the description covers the main use cases, return types, batch vs single distinction, and error handling. It adequately informs an agent about how to use the tool effectively, though could mention potential limitations or dependencies more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 64% schema description coverage, the description adds significant meaning beyond the schema: explains that 'mdi:' prefix is optional and aliases honored, provides example MDI names, clarifies 'text' mutual exclusivity, recommends icon_scale for different setups, and describes transparent_bg usage. This adds value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Generate one or many PNG icons' with a specific verb and resource. It distinguishes from sibling tools by specifying icon creation, not actions or page writing, and provides context on icon sizes and shapes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explains when to use single icon vs batch mode, mentions mutual exclusivity of 'icon' and 'text', and advises using batch for many icons to avoid timeouts. It also clarifies that titles belong on streamdeck_write_page, guiding correct usage. Lacks explicit when-not-to-use but the guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Reinstall the plugin even if it already exists. Useful after upgrading streamdeck-mcp. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses idempotency, return value when already present (installed=false), and effect of force=true. Could add more detail on permissions or side effects, but current level is good for a single-parameter tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences. First sentence states main action, second explains why the plugin exists, third covers idempotency and auto-install. Every sentence earns its place, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one optional parameter, no output schema, and clear sibling context, the description fully covers purpose, behavior, idempotency, and usage guidance. No missing information for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and schema describes force. Description adds value by explaining that force=true is useful after upgrading, which goes beyond the schema description. No other parameters to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'install' and specific resource 'streamdeck-mcp Stream Deck plugin' into the Elgato Plugins directory. Distinguishes from siblings by explaining that streamdeck_write_page auto-installs it, so most callers don't need this tool directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on when to use (installing the plugin) and when not (most callers should rely on auto-install from streamdeck_write_page). Mentions force parameter for reinstalling after upgrade. Does not name a specific alternative tool explicitly, but the auto-install note serves as guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a profile page by profile name or ID and page index or directory ID.
| Name | Required | Description | Default |
|---|---|---|---|
| profile_name | No | Exact profile name as shown in the Elgato app. | |
| profile_id | No | Directory-based profile ID, usually the .sdProfile folder name without the suffix. | |
| page_index | No | Zero-based page index from streamdeck_read_profiles. Accepts int or a string form. | |
| directory_id | No | Page directory ID from streamdeck_read_profiles. This is the safest target for updates. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Read' implying no side effects, but does not disclose any potential behavioral traits such as whether it accesses the file system, requires app permissions, or is safe to call repeatedly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence. It could be slightly improved by splitting into two sentences for readability, but it is effective and free of waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so description should ideally indicate what the tool returns (e.g., page data). It does not. With 4 parameters and none required, the description is adequate but leaves the agent unsure of the return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description explains parameters' roles (by profile name/ID and page index/directory ID) but adds no further syntax or format detail beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a profile page, specifying the resources (profile name/ID and page index/directory ID). It distinguishes from siblings like streamdeck_read_profiles (which lists profiles) and streamdeck_write_page (which writes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to read a specific page) but does not explicitly mention when not to use or provide alternatives. For example, it does not suggest using streamdeck_read_profiles first to obtain page indices or directory IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Stream Deck desktop profiles from the active ProfilesV3 or ProfilesV2 directory.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It states what the tool does but omits details like whether it is read-only, what 'active' means, or any error conditions. The side-effect nature is implied but not confirmed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence. While short, it could be slightly expanded to include key behavioral context without becoming verbose. For a simple list tool, it is appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and a simple list operation, the description should clarify the 'active' directory concept, expected output, and any permissions. It is insufficiently complete for an agent to confidently invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline score is 4. The description does not need to add parameter-specific information as there are no parameters to describe.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and resource 'Stream Deck desktop profiles', clearly distinguishing from sibling tools like streamdeck_create_action or streamdeck_restart_app. The mention of 'active ProfilesV3 or ProfilesV2 directory' adds further specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives, nor any conditions for use. The description does not mention prerequisites or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restart the macOS Stream Deck desktop app after profile changes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions restarting, which implies closing and reopening the app, but it does not disclose potential side effects like loss of unsaved work or confirmation prompts. Without annotations, more detail would be helpful, but the behavior is straightforward.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that conveys the purpose and context without any redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity with no parameters and no output schema, the description adequately covers its purpose and usage context. It could mention platform specificity but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and schema description coverage is 100%. No additional parameter information is needed, so baseline score 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool restarts the macOS Stream Deck desktop app, which is specific and distinct from sibling tools like create, read, write, or install.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes 'after profile changes,' providing clear context for when to use the tool, though it does not explicitly state when not to use it or offer alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| profile_name | No | ||
| profile_id | No | ||
| page_index | No | Zero-based page index. Accepts int or string form. | |
| directory_id | No | ||
| page_name | No | Optional page name stored in the page manifest. | |
| buttons | No | Buttons to write. Use streamdeck_create_action to build Open or script-backed actions. Accepts a JSON array or a JSON-encoded string — some MCP clients stringify nested arrays in transit. | |
| clear_existing | No | If true, replace the page contents with the provided buttons. Defaults to true. Accepts bool or string form. | |
| create_new | No | Create a new page instead of updating an existing one. | |
| make_current | No | When true, make the page the active current page after writing. | |
| auto_quit_app | No | If true and the Elgato Stream Deck desktop app is running, quit it (graceful AppleScript first, then killall) before writing. Required when the app is running or the write will raise an error. Defaults to false so callers must explicitly consent to quitting it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description shoulders the full burden of behavioral disclosure. It transparently warns about the app overwriting behavior, the refusal to write without auto_quit_app, and the need to restart. However, it does not detail error handling, idempotency, or what happens if the app is not installed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the purpose, and includes only essential warnings and follow-up instructions. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, no output schema, and no annotations, the description covers the core behavior and critical parameters well. It mentions the restart requirement. However, it does not describe the return value or confirmation message, which would be helpful for an agent to verify success.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 70% (high), so baseline is 3. The description adds value beyond the schema by highlighting the auto_quit_app parameter's critical role and explaining the consequence of not using it. Other parameters are well-documented in the schema, so the extra description is concise and targeted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create a new page or replace/update an existing Stream Deck desktop page manifest.' It specifies the verb (create/replace/update) and the resource (page manifest), and distinguishes from sibling tools that deal with actions, icons, or reading pages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use and when-not-to-use guidance, including the critical warning about the app overwriting manifests on quit, the requirement to pass auto_quit_app=True when the app is running, and the follow-up recommendation to call streamdeck_restart_app to apply changes. This clearly differentiates usage from other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0streamdeck_create_actionstreamdeck_create_iconstreamdeck_install_mcp_pluginstreamdeck_read_pagestreamdeck_read_profilesstreamdeck_restart_appstreamdeck_write_pageScored across 7 tools
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.
All tools follow a consistent 'streamdeck_verb_noun' pattern (e.g., create_action, read_page, restart_app). The naming is predictable and uniform.
With 7 tools, the server is well-scoped for the domain of Stream Deck profile management, covering essential operations without excess or omission.
The tool set covers core workflows (creating icons, actions, pages, profiles) but lacks delete operations for pages or actions, which is a minor gap.
Multistream to Twitch, YouTube and Kick; generate OBS overlays from a plain-English prompt.
Design, save, and run outcome-aligned AI workflows and verifiers, with reliable image output.
Build, validate, deploy — HTTP APIs, cron jobs, webhooks and MCP tools — from your AI client.
Contextual prompts and agent skills for 140+ AI platforms.
