streamdeck-mcp

Overview Schema Source Related Servers Discussions Admin

streamdeck_write_page

Create, replace, or update a Stream Deck desktop page manifest with buttons, actions, dial layouts, and settings; restart the app afterward to show edits on the device.

Instructions

Create a new page or replace/update an existing Stream Deck desktop page manifest. Authoring preference order: (1) paste a native 'action' from streamdeck_find_actions or streamdeck_read_page's button.raw — best for installed plugins with private Settings; (2) synthesize via plugin_uuid + action_uuid + settings from streamdeck_read_plugins when no configured instance exists; (3) script-backed Open actions via path / streamdeck_create_action for custom automation; also supports page-nav (action_type) and the bundled MCP dial. Validation: unknown plugin_uuid/action_uuid raises a clear error listing what is installed; missing settings fields are reported non-fatally in the result's 'warnings'. 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.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "streamdeck_write_page"
  }
}

Input Schema

Name	Required	Description
`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.
`page_name`	No	Optional page name stored in the page manifest.
`create_new`	No	Create a new page instead of updating an existing one.
`page_index`	No	Zero-based page index. Accepts int or string form.
`profile_id`	No
`directory_id`	No
`make_current`	No	When true, make the page the active current page after writing.
`profile_name`	No
`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.
`clear_existing`	No	If true, replace the page contents with the provided buttons. Defaults to true. Accepts bool or string form.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.4.0Nov 4, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so: it discloses validation failure behavior ('unknown plugin_uuid/action_uuid raises a clear error listing what is installed'), non-fatal missing settings reported in 'warnings', and a critical environmental hazard — the Elgato app overwrites manifests on quit so writes are lost. It also documents the refusal guard and the exact auto_quit_app escalation path (AppleScript then killall), which no annotation or schema field conveys.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: purpose first, then authoring order, then validation, then the high-stakes app-conflict warning. The IMPORTANT marker is used well. It runs long, but nearly every sentence carries operational information rather than restating the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter mutation tool with no annotations and no output schema, the definition covers the highest-risk unknowns: data-loss hazard, consent flag, validation semantics, and the follow-up restart. The remaining gap is return-value shape and the three unexplained profile/directory identifiers.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 70%, so most field-level meaning already lives in the schema (key indexing, controller scoping, encoder_layout variants, icon sizes). The description adds real value by explaining which parameter combinations to use for which authoring mode, though it leaves profile_id, directory_id, and profile_name unexplained in both description and schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('Create a new page or replace/update an existing Stream Deck desktop page manifest') and immediately scopes it against siblings by naming streamdeck_read_page, streamdeck_find_actions, streamdeck_read_plugins, and streamdeck_create_action. An agent can distinguish this write tool from the read/create helpers without inspecting any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit ranked authoring strategy (1: paste native action from find_actions/read_page, 2: synthesize from plugin_uuid+action_uuid+settings via read_plugins, 3: script-backed Open actions via path/create_action), plus the post-write step 'call streamdeck_restart_app'. This is when-to-use and which-alternative guidance stated directly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server