opendeck-mcp

# opendeck-mcp

<!-- mcp-name: io.github.kastro5/opendeck-mcp -->

Set up your [OpenDeck](https://github.com/nekename/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](https://modelcontextprotocol.io) 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](https://github.com/kastro5/opendeck-ulanzi-d200).

## Contents

- [What it can do](#what-it-can-do)
- [Install](#install)
  - [Upgrading](#upgrading)
  - [Other MCP clients](#other-mcp-clients)
  - [From another computer](#from-another-computer)
  - [As an OpenDeck plugin](#as-an-opendeck-plugin)
- [Using it](#using-it)
- [How it works](#how-it-works)
- [Safety](#safety)
- [Tools](#tools)
- [Limitations](#limitations)
- [Troubleshooting](#troubleshooting)
- [Development](#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](https://docs.astral.sh/uv/) and Claude Code (or another MCP client, see
below). uv fetches a suitable Python by itself.

```sh
claude mcp add opendeck --scope user -- uvx opendeck-mcp@0.4.0
```

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

It's on [PyPI](https://pypi.org/project/opendeck-mcp/) and in the
[MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.kastro5/opendeck-mcp`. To run
straight from GitHub instead: `uvx --from git+https://github.com/kastro5/opendeck-mcp@v0.4.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`):

| Variable | Default (Windows) |
|---|---|
| `OPENDECK_CONFIG_DIR` | `%APPDATA%\opendeck` |
| `OPENDECK_EXE` | `%LOCALAPPDATA%\OpenDeck\opendeck.exe` |
| `OPENDECK_LOG_DIR` | `%LOCALAPPDATA%\opendeck\logs` |
| `OPENDECK_MCP_DATA_DIR` | `%LOCALAPPDATA%\opendeck-mcp` (the server's own plan, backups and cache) |
| `OPENDECK_MCP_HA_VERIFY_TLS` | `1`; set `0` for a Home Assistant on https with a self-signed certificate |
| `OPENDECK_MCP_TOKEN` | the HTTP token (default: generated once, see below) |

### Upgrading

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

```sh
claude mcp remove opendeck --scope user
claude mcp add opendeck --scope user -- uvx opendeck-mcp@0.4.0
```

The first apply after an upgrade also updates the companion bridge plugin (see
[How it works](#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:

```json
{
  "mcpServers": {
    "opendeck": {
      "command": "uvx",
      "args": ["opendeck-mcp@0.4.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](https://tailscale.com) or another private network is the recommended way
in; every request also needs a token.

On the OpenDeck PC (Windows):

```sh
uvx opendeck-mcp@0.4.0 install-autostart --host <tailscale-ip>
uvx opendeck-mcp@0.4.0 token --host <tailscale-ip>
```

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:

```sh
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 <name>`; 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 <ip>` 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
   `dev.kastro5.opendeck-mcp.sdPlugin.zip` from the
   [latest release](https://github.com/kastro5/opendeck-mcp/releases/latest), extract it into
   OpenDeck's `plugins` folder (`%APPDATA%\opendeck\plugins` on Windows) and restart OpenDeck.
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 →)
```

| Slot | Meaning |
|---|---|
| `r1c1` | row 1, column 1 |
| `key13` | raw position 13 (0-based) |
| `dial1` | first dial |
| `touch1` | first touchpoint |
| `r1c1/child2` | second action in