OpenDeck

opendeck-mcp

Set up your OpenDeck stream controller by asking an AI agent:

"Put a Multi Action on the top-left key that mutes my mic and opens Discord, make a 'Gaming'

profile from my default one, and switch to it whenever Steam is focused."

opendeck-mcp is an MCP server. It lets Claude Code (or any MCP client) read your decks, profiles and plugins, stage changes, show you a diff, and then apply them, with a backup you can undo. It works with any device OpenDeck drives: Elgato Stream Decks and plugin-provided devices such as the Ulanzi D200H/D200X.

Contents

• What it can do
• Install
• Upgrading
• Other MCP clients
• From another computer
• As an OpenDeck plugin
• Using it
• How it works
• Safety
• Tools
• Limitations
• Troubleshooting
• Development

What it can do

• See everything: devices with their grid size, dials and touchpoints; profiles; every key's action, title and settings; and installed plugins with their actions.
• Edit keys: place, update (title, font, colour, image, settings), clear, move, swap or copy keys, dials and touchpoints, across profiles and devices.
• Multi and Toggle Actions: add and remove the actions inside them, and set the delays between them.
• Profiles: create, duplicate, rename (references to the old name are updated too) and delete profiles, including Folder/Name profiles, and choose which one each device starts on.
• App switching: switch a device to a profile automatically when an app is focused.
• Plugins:
• search the same catalogue as OpenDeck's Plugin Manager, plus the Elgato plugin archive;
• install, update and remove plugins;
• read and write plugin settings, with secrets redacted;
• read plugin logs.
• Instant edits: title, image and settings tweaks to a key on the profile a device is showing apply at once, with no restart; undo_live takes them back.
• Icons and folders: make key images from text, emoji, ~3,400 brand logos or ~7,400 symbols, and folder keys that open a sub-profile with a Back key.
• Pictures: render_profile shows the deck as OpenDeck draws it, with staged changes outlined or before and after side by side, so you can check a layout before applying it.
• Home Assistant: find entities by name, area or domain, and get ready-made settings for a key that controls one, using the login already saved in the Home Assistant plugin.
• Undo: every apply takes a backup, and restore_backup puts things back.

Install

You need OpenDeck 2.14, uv and Claude Code (or another MCP client, see below). uv fetches a suitable Python by itself.

claude mcp add opendeck --scope user -- uvx opendeck-mcp@0.5.0

Then restart Claude Code and ask it something like *"what's on my OpenDeck?"*.

It's on PyPI and in the MCP Registry as io.github.kastro5/opendeck-mcp. To run straight from GitHub instead: uvx --from git+https://github.com/kastro5/opendeck-mcp@v0.5.0 opendeck-mcp.

OpenDeck's folders are found automatically. If yours live somewhere unusual, override them with environment variables (claude mcp add … -e NAME=value):

Upgrading

The version is pinned in the command, so replace the registration with the new tag:

claude mcp remove opendeck --scope user

claude mcp add opendeck --scope user -- uvx opendeck-mcp@0.5.0

The first apply after an upgrade also updates the companion bridge plugin (see How it works), in the same restart.

Other MCP clients

Any client that can start a stdio server works. The usual JSON configuration (Claude Desktop, Cursor, VS Code and others) is:

{

"mcpServers": { "opendeck": { "command": "uvx", "args": ["opendeck-mcp@0.5.0"] } } }

From another computer

The server has to run on the PC that runs OpenDeck, inside your logged-in desktop session: it restarts OpenDeck and talks to it through its command line, which doesn't work from a service or an SSH session. To use it from another machine (a laptop, a dev VM), serve it over HTTP there and connect to it. Tailscale or another private network is the recommended way in; every request also needs a token.

On the OpenDeck PC (Windows):

uvx opendeck-mcp@0.5.0 install-autostart --host <tailscale-ip>

uvx opendeck-mcp@0.5.0 token --host

The first command puts a small script in your Startup folder that starts the server, without a window, at every logon, and starts it now. The second prints the command to run on the other machine:

claude mcp add --transport http opendeck http://<tailscale-ip>:8765/mcp --header "Authorization: Bearer <token>"

• tailscale ip -4 shows the address. The server refuses 0.0.0.0 (every network) unless you add --allow-all-interfaces.
• To connect by name (e.g. a MagicDNS name), add --allowed-host ; other Host headers are rejected.
• opendeck-mcp token --reset makes a new token, and opendeck-mcp uninstall-autostart removes the autostart and stops the server.
• Windows Firewall must allow inbound TCP 8765 on that network; it asks the first time if it isn't already allowed.
• On Linux or macOS, run opendeck-mcp serve --host from a systemd user service or LaunchAgent.

As an OpenDeck plugin

The same server also comes as an OpenDeck plugin, which needs neither uv nor a terminal: OpenDeck starts and stops it, and it serves MCP over HTTP. Windows and Linux; macOS isn't built.

1. Install OpenDeck MCP from OpenDeck's plugin store once it's listed there, or download io.github.kastro5.opendeck-mcp.sdPlugin.zip from the latest release, extract it into OpenDeck's plugins folder (%APPDATA%\opendeck\plugins on Windows) and restart OpenDeck. Upgrading from before 0.5.0: the plugin's ID changed from dev.kastro5.opendeck-mcp to io.github.kastro5.opendeck-mcp, so remove the old one in the Plugins tab; its settings carry over.
2. In OpenDeck's Plugins tab, click the gear next to OpenDeck MCP. A page opens in your browser with the claude mcp add … command (token included) and a Copy button. Run it, then restart Claude Code.

By default it listens on 127.0.0.1:8765, for clients on the same PC. To reach it from another machine, pick a network address on the same page, ideally the Tailscale one; the listener restarts at once and the page shows the new command. The page also makes a new token. It closes itself after 10 minutes; the gear opens a fresh one.

Differences from the uvx server:

• Applying goes through a helper. Applying restarts OpenDeck, and the plugin with it, so apply_changes and restore_backup hand the work to a short-lived helper and return straight away. The result arrives with your next tool call, about 10 seconds later.
• No bridge plugin. The plugin records device geometry itself.
• Same token and data folder as opendeck-mcp serve. Don't run both on the same address and port: the second one can't listen, and the gear page (and get_overview) says so.
• It can't update or remove itself; do that from OpenDeck's Plugins tab.
• The Linux build is compiled and smoke-tested in CI but hasn't been tried on a real deck.
• Not for the Flatpak build of OpenDeck: applying needs to restart OpenDeck from outside its sandbox, so the plugin refuses to apply there.
• The executable isn't code-signed, so antivirus software may ask about it the first time.

Using it

Just describe what you want. Under the hood, the agent:

1. calls get_overview and show_profile to see your devices and keys;
2. uses list_actions / describe_action to find the right action and learn its settings;
3. stages edits with set_key, add_child, manage_profile and so on;
4. calls preview_changes (and render_profile for a picture), shows you the result, and waits for your OK;
5. calls apply_changes, which restarts OpenDeck for a few seconds and reports the backup id.

Small tweaks skip all that. Changing an existing key's title, image or settings on the profile a connected device is showing happens instantly, without a restart, and undo_live reverses it. Title style, the shown state, other profiles and every structural change still go through staging.

For example, *"make a Fusion 360 profile with keys for my most-used sketch and solid tools, put the rest in a folder, and switch to it whenever Fusion is in front"* builds a profile of Simulate Input keys sending Fusion's shortcuts, with icons from make_icon, a "More" folder and the app rule.

Keys are addressed the way show_profile draws them:

     c1              c2              c3              c4              c5

r1 Multi Action "GitHub" Toggle Action · · r2 · Entity (custo… · Switch Profile · r3 Device Bright… · "rew" · (wide →)

How it works

OpenDeck has no API for changing its layout. It keeps profiles in memory and overwrites any file edited while it runs. So opendeck-mcp works on the files, with OpenDeck stopped:

1. Staging. Each edit is recorded as an operation in a plan. Nothing is written yet. show_profile shows staged edits marked with *.
2. Applying.

• First, OpenDeck is asked to save its in-memory state. This sends a profile switch through its command line, which makes it write the selected profile.
• Then OpenDeck and its plugin processes are stopped.
• The plan is replayed onto the freshly read files. If something you staged was changed in OpenDeck's UI in the meantime, apply reports a conflict and doesn't write anything.
• The files are backed up, written atomically, read back and re-validated. If anything fails, the backup is restored automatically.
• Finally, OpenDeck is started again, detached and hidden.

1. Faithful files. Action data is rebuilt from plugin manifests exactly as OpenDeck builds it, and JSON is written byte-for-byte in OpenDeck's format. A profile OpenDeck can't read gets replaced by an empty one, so every write is validated twice.
2. Device geometry. OpenDeck doesn't store a device's rows × columns anywhere, so the first apply also installs a tiny companion plugin, *OpenDeck MCP Bridge* (no actions, about 60 lines of JavaScript). It records the geometry OpenDeck reports to plugins into its own settings file, where the server reads it. It's versioned with the server, so a new release updates it on its next apply.
3. Images. New key images are stored as data: URLs. OpenDeck accepts these and converts them to files itself on its next save.

Insta