OpenDeck

opendeck-mcp

只需向 AI agent 提出要求，即可设置你的 OpenDeck 流控设备：

“在左上角按键上放置一个 Multi Action，用于静音我的麦克风并打开 Discord；从我的默认配置创建一个名为‘Gaming’的配置，并在 Steam 获得焦点时切换到该配置。”

opendeck-mcp 是一个 MCP 服务。它允许 Claude Code（或任何 MCP 客户端） 读取你的设备布局、配置和插件、暂存更改、显示差异，然后应用更改，并创建可撤销的备份。它适用于 OpenDeck 驱动的任何设备：Elgato Stream Deck 和由插件提供的设备，例如 Ulanzi D200H/D200X。

目录

• 功能
• 安装
  • 升级
  • 其他 MCP 客户端
  • 从另一台计算机连接
  • 作为 OpenDeck 插件使用
• 使用方法
• 工作原理
• 安全性
• 工具
• 限制
• 故障排除
• 开发

功能

• **查看所有内容：**设备及其网格大小、旋钮和触控点；配置；每个按键的操作、标题和设置；以及已安装的插件及其操作。
• **编辑按键：**在不同配置和设备间放置、更新（标题、字体、颜色、图像、设置）、清除、移动、交换或复制按键、旋钮和触控点。
• **Multi 和 Toggle Action：**添加和移除其中的操作，并设置操作之间的延迟。
• **配置：**创建、复制、重命名（也会更新对旧名称的引用）和删除配置，包括 Folder/Name 配置，并选择每台设备启动时使用的配置。
• **应用切换：**当某个应用获得焦点时，自动将设备切换到相应配置。
• 插件：
  • 搜索与 OpenDeck 插件管理器相同的目录，以及 Elgato 插件存档；
  • 安装、更新和移除插件；
  • 读取和写入插件设置，并对机密信息进行隐藏处理；
  • 读取插件日志。
• **即时编辑：**对设备当前显示的配置中的按键进行标题、图像和设置调整后，会立即生效，无需重启；undo_live 可撤销这些调整。
• **图标和文件夹：**使用文本、表情符号、约 3,400 个品牌徽标或约 7,400 个符号制作按键图像；还可创建打开子配置并带有返回按键的文件夹按键。
• 图片：render_profile 会按照 OpenDeck 的绘制方式显示设备布局，并以轮廓标出暂存的更改，或并排显示更改前后的布局，方便你在应用前检查。
• **Home Assistant：**按名称、区域或域查找实体，并使用 Home Assistant 插件中已保存的登录信息，获取控制实体的按键预设设置。
• **撤销：**每次应用更改都会创建备份；restore_backup 可还原内容。

安装

你需要 OpenDeck 2.14、uv 和 Claude Code（或其他 MCP 客户端，见下文）。uv 会自行获取合适的 Python。

claude mcp add opendeck --scope user -- uvx [email protected]

然后重启 Claude Code，并询问类似 “我的 OpenDeck 上有什么？” 的问题。

它已发布到 PyPI 和 MCP Registry，名称为 io.github.kastro5/opendeck-mcp。若要直接从 GitHub 运行：uvx --from git+https://github.com/kastro5/[email protected] opendeck-mcp。

OpenDeck 的文件夹会自动查找。如果你的文件夹位于不常见的位置，可以使用环境变量覆盖路径（claude mcp add … -e NAME=value）：

变量	默认值（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（服务自己的计划、备份和缓存）
OPENDECK_MCP_HA_VERIFY_TLS	1；如果 Home Assistant 使用带自签名证书的 https，请设为 0
OPENDECK_MCP_TOKEN	HTTP 令牌（默认：生成一次，见下文）

升级

命令中固定了版本，因此请用新的标签替换注册项：

claude mcp remove opendeck --scope user
claude mcp add opendeck --scope user -- uvx [email protected]

升级后的首次应用也会更新配套的桥接插件（见工作原理），并在同一次重启中完成。

其他 MCP 客户端

任何能够启动 stdio 服务的客户端都可以使用。常见的 JSON 配置（Claude Desktop、Cursor、VS Code 等）如下：

{
  "mcpServers": {
    "opendeck": {
      "command": "uvx",
      "args": ["[email protected]"]
    }
  }
}

从另一台计算机连接

服务必须在运行 OpenDeck 的电脑上、已登录的桌面会话中运行：它会重启 OpenDeck，并通过 OpenDeck 的命令行与其通信，因此无法从服务或 SSH 会话中运行。若要从另一台设备（笔记本电脑、开发 VM）使用，请在该电脑上通过 HTTP 提供服务并连接到它。建议通过 Tailscale 或其他私有网络连接；每个请求还需要令牌。

在运行 OpenDeck 的电脑上（Windows）：

uvx [email protected] install-autostart --host <tailscale-ip>
uvx [email protected] token --host <tailscale-ip>

第一个命令会在“启动”文件夹中放入一个小脚本，让服务在每次登录时无窗口启动，并立即启动服务。第二个命令会打印出要在另一台设备上运行的命令：

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

• tailscale ip -4 会显示地址。除非添加 --allow-all-interfaces，否则服务会拒绝 0.0.0.0（所有网络）。
• 若要通过名称连接（例如 MagicDNS 名称），请添加 --allowed-host <name>；其他 Host 标头都会被拒绝。
• opendeck-mcp token --reset 会生成新令牌，opendeck-mcp uninstall-autostart 会移除自动启动项并停止服务。
• Windows 防火墙必须允许该网络上的入站 TCP 8765 端口；如果尚未允许，系统会在首次使用时提示。
• 在 Linux 或 macOS 上，请通过 systemd 用户服务或 LaunchAgent 运行 opendeck-mcp serve --host <ip>。

作为 OpenDeck 插件

同一服务也提供 OpenDeck 插件版本，无需 uv 或终端： OpenDeck 会启动和停止它，并通过 HTTP 提供 MCP 服务。支持 Windows 和 Linux；尚未构建 macOS 版本。

1. 在 OpenDeck 的插件商店上架后，从商店安装 OpenDeck MCP；或者从最新版本下载 dev.kastro5.opendeck-mcp.sdPlugin.zip，解压到 OpenDeck 的 plugins 文件夹（Windows 上为 %APPDATA%\opendeck\plugins），然后重启 OpenDeck。
2. 在 OpenDeck 的 Plugins 标签页中，点击 OpenDeck MCP 旁的齿轮。浏览器中会打开一个页面，其中包含 claude mcp add … 命令（已包含令牌）和 Copy 按钮。运行该命令，然后重启 Claude Code。

默认情况下，它会监听 127.0.0.1:8765，供同一台电脑上的客户端使用。如需从另一台设备访问，请在同一页面选择一个网络地址，最好选择 Tailscale 地址；监听器会立即重启，页面也会显示新的命令。页面还会生成新令牌。页面会在 10 分钟后自动关闭；点击齿轮会打开一个新页面。

与 uvx 服务的区别：

• 应用更改需通过辅助程序完成。 应用更改会重启 OpenDeck 及其插件，因此 apply_changes 和 restore_backup 会将任务交给一个短暂运行的辅助程序，并立即返回。结果会在大约 10 秒后的下一次工具调用时返回。
• 无需桥接插件。 插件会自行记录设备布局。
• 使用与 opendeck-mcp serve 相同的令牌和数据文件夹。 请勿在相同地址和端口上同时运行两者：第二个实例无法监听，齿轮页面（以及 get_overview）会说明原因。
• 它无法自行更新或移除；请在 OpenDeck 的 Plugins 标签页中操作。
• Linux 版本已在 CI 中编译并通过冒烟测试，但尚未在真实设备上试用。
• 不适用于 OpenDeck 的 Flatpak 版本：应用更改需要从沙盒外部重启 OpenDeck，因此插件会拒绝在该版本中应用更改。
• 可执行文件未经代码签名，因此杀毒软件可能会在首次运行时询问是否允许。

使用方法

只需描述你想要什么。Agent 在后台会：

1. 调用 get_overview 和 show_profile，查看你的设备和按键；
2. 使用 list_actions / describe_action 查找合适的操作并了解其设置；
3. 使用 set_key、add_child、manage_profile 等暂存编辑；
4. 调用 preview_changes（并调用 render_profile 生成图片），向你展示结果，然后等待你的确认；
5. 调用 apply_changes，重启 OpenDeck 几秒钟，并报告备份 ID。

小幅调整不必经过这些步骤。更改已连接设备当前显示的配置文件中某个现有按键的标题、图像或设置，会立即生效，无需重启；undo_live 可撤销更改。标题样式、显示状态、其他配置文件以及所有结构性更改仍需先暂存。

例如，“创建一个 Fusion 360 配置文件，包含我最常用的草图和实体工具按键，把其余工具放到一个文件夹里，并在 Fusion 处于前台时自动切换到该配置文件”，会创建一个配置文件，其中包含发送 Fusion 快捷键的 Simulate Input 按键、来自 make_icon 的图标、一个“More”文件夹以及应用规则。

按键的地址与 show_profile 绘制时使用的方式一致：

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

插槽	含义
r1c1	第 1 行，第 1 列
key13	原始位置 13（从 0 开始计数）
dial1	第一个旋钮
touch1	第一个触点
r1c1/child2	Multi 或 Toggle Action 中的第二个操作

工作原理

OpenDeck 没有用于更改布局的 API。它会将配置文件保存在内存中，并覆盖运行期间编辑的任何文件。因此，opendeck-mcp 会在 OpenDeck 停止时操作文件：

1. 暂存。 每次编辑都会作为一项操作记录在计划中。此时不会写入任何内容。 show_profile 会用 * 标记暂存的编辑。
2. 应用。
   • 首先，要求 OpenDeck 保存其内存中的状态。这会通过其命令行发送配置文件切换指令，使其写入所选配置文件。
   • 然后停止 OpenDeck 及其插件进程。
   • 将计划应用到重新读取的文件上。如果你暂存的内容在此期间被 OpenDeck 界面更改，应用操作会报告冲突，且不会写入任何内容。
   • 先备份文件，再以原子方式写入、读回并重新验证。如果任何步骤失败，系统会自动恢复备份。
   • 最后，重新启动 OpenDeck，并使其在后台运行且隐藏。
3. 忠实保留文件。 操作数据会根据插件清单重建，方式与 OpenDeck 完全一致；JSON 也会按照 OpenDeck 的格式逐字节写入。如果 OpenDeck 无法读取某个配置文件，就会将其替换为空配置文件，因此每次写入都会经过两次验证。
4. 设备几何信息。 OpenDeck 不会在任何地方存储设备的行数 × 列数，因此首次应用时还会安装一个小型配套插件 OpenDeck MCP Bridge（没有操作，约 60 行 JavaScript）。它会将 OpenDeck 报告给插件的几何信息记录到自己的设置文件中，服务端会从中读取信息。该插件与服务端使用相同的版本，因此新版本会在下次应用时更新它。
5. 图片。 新的按键图片会以 data: URL 的形式存储。OpenDeck 接受这种格式，并会在下次保存时自行将其转换为文件。

即时编辑

标题和图片会通过命令行（--process-message）发送给正在运行的 OpenDeck，作为 setTitle 和 setImage 事件。设置会通过 OpenDeck 的本地插件 WebSocket 发送，并模拟按键的设置面板，因为只有通过这条路径，OpenDeck 才会通知插件设置已更改。随后会要求 OpenDeck 保存，并检查文件。每次编辑前，旧标题、图片（以字节形式）和设置都会写入服务端数据文件夹中的 live_journal.jsonl，undo_live 会重放其中的记录。

安全

• 确认后才会进行任何更改。 暂存工具不会触碰 OpenDeck。apply_changes、 restore_backup 和插件安装都需要再次调用并设置 confirm=true。
• 备份。 每次应用更改前，都会先将 profiles/、images/、applications.json 以及其他 将要触碰的内容复制到 %LOCALAPPDATA%\opendeck-mcp\backups。最多保留最近 30 份备份（至少始终保留 5 份）。 恢复时也会先备份当前状态。备份包含插件设置，其中可能有机密信息，因此备份只保留在你的计算机上。
• 机密信息会被脱敏。 所有看起来像凭据的内容（令牌、密码、API 密钥、JWT、Bearer 值等）都会在设置、差异、示例和日志中显示为 «redacted»。传回 «redacted» 会保留已存储的值。
• 高风险键会标记出来。 Run Command 键会运行命令，Simulate Input 键会在当前聚焦的窗口中输入内容，而带有非 Web URI 的 Open URL 键可能会启动程序。暂存时和预览中都会以 ⚠ 标记这些键。
• 插件是第三方代码。 stage_plugin 会先下载并检查插件：作者、版本、sha256、运行方式、支持的平台，以及目录中的 AI-assisted 标记。只有你同意后，才会暂存安装。内置插件无法移除。
• Home Assistant。 Home Assistant 工具会复用 Home Assistant 插件中保存的服务器 URL 和访问令牌。令牌只会发送到该服务器，绝不会显示。ha_call_service 会操作你的实际家庭设备，因此需要再次调用并设置 confirm=true。
• 即时编辑不会备份。 即时编辑不会经过应用流程，因此之前的标题、图片和设置会保存在日志中（最多记录最近 200 次编辑），供 undo_live 重放。
• HTTP 令牌是你设备的访问密钥。 任何能访问该端口且持有令牌的人，都可以更改键、安装插件，并通过 Run Command 键运行程序。请将服务器保持在专用地址上；如果令牌泄露，请运行 opendeck-mcp token --reset。
• 版本检查。 除非你明确允许，否则在 OpenDeck 版本不是 2.14.x 时，应用操作会拒绝运行。

网络和文件

• 互联网： 仅用于插件目录和插件下载（find_plugins、stage_plugin），以及分别从 jsDelivr 获取一次并缓存的 render_profile 标题字体和 make_icon 图标集。除此之外不会进行任何网络访问，也没有遥测。
• 本地网络： 仅在使用 Home Assistant 工具时连接你的 Home Assistant。
• %LOCALAPPDATA%\opendeck-mcp 中的文件：plan.json（暂存的更改）、backups/、 live_journal.jsonl、icons/（由 make_icon 创建）、cache/（目录、字体、图标集）、 device_overrides.json，以及用于 HTTP 的 http_token 和 http.log。删除此文件夹即可重置所有内容。

工具

类型	工具
读取	get_overview、show_profile、render_profile、list_actions、describe_action、get_plugin_settings、read_logs、get_app_rules、find_plugins、find_icons、preview_changes、list_backups
暂存	set_key、update_key、clear_key、move_key、add_child、remove_child、set_multi_delays、make_folder、manage_profile、set_app_rule、set_plugin_settings、stage_plugin、discard_changes、set_device_layout
图标	make_icon（将 PNG 保存下来，供 image 使用）
应用	apply_changes、restore_backup、undo_live
Home Assistant	ha_search、ha_describe_entity、ha_call_service

限制

• 应用更改会重启 OpenDeck（约 5 秒）。已打开的设置面板中未保存的更改会丢失，插件也会重启。
• 部分设置需要示例。 OpenDeck 自带操作和 Starter Pack 的设置已有详细说明。对于其他插件，Agent 会根据插件设置页面上的提示和你现有的键进行操作。如果这些信息还不够，请先放置该操作，再在 OpenDeck 界面中完成设置。
• 应用规则名称。 应用规则会匹配 OpenDeck 为当前聚焦的应用指定的名称：在 Windows 上是可执行文件的说明（例如 Autodesk Fusion、Visual Studio Code），其他系统上则是文件名。get_app_rules 会列出当前已打开应用的确切名称。
• 已测试的平台。 已在 Windows 11、OpenDeck 2.14.1、Ulanzi D200H 和 Home Assistant 上测试。macOS 和 Linux 的路径及进程处理逻辑已编写，但未经测试。
• 实时控制有限。 标题、图像和设置编辑会立即生效；其他更改都需要重启。它不会实时按键或切换配置文件。
• 图片接近实际效果，但并非完全一致。 render_profile 无法读取插件运行时绘制的图像（例如时钟、实时 Home Assistant 状态），除非 OpenDeck 已保存这些图像；OpenDeck 自带的 Multi/Toggle Action 图标也只是仿制图。
• 已打开的设置面板会停止更新。 即时编辑设置后，OpenDeck 窗口中该键已打开的设置面板会停止更新，直到重新打开。

故障排除

• “未找到 OpenDeck 可执行文件”／“未找到配置文件夹”：设置 OPENDECK_EXE／OPENDECK_CONFIG_DIR（参见安装）。
• 应用更改时提示 OpenDeck 版本未经测试。 查看更新日志，确认是否有支持你所用版本的发行版；apply_changes(allow_untested_version=true) 可覆盖此限制，但风险由你自行承担，并会创建备份。
• 应用更改时报告冲突。 你暂存的键与此同时在 OpenDeck 中发生了更改。查看 preview_changes，然后丢弃并重新暂存，或使用 on_conflict="skip" 应用更改。
• 设备显示“几何结构未知”。 桥接插件会在首次应用更改时安装，并识别设备布局。在此之前，set_device_layout 可手动设置行数和列数。
• 撤销应用更改： 使用 list_backups，然后使用 restore_backup。
• 插件：齿轮页面显示“未提供服务”。 通常是另一个程序占用了该端口，例如在相同地址上运行的 opendeck-mcp serve。在页面上选择其他端口，或停止另一个服务（opendeck-mcp uninstall-autostart）。插件日志位于 OpenDeck 日志文件夹中的 logs\plugins\dev.kastro5.opendeck-mcp.sdPlugin.log。
• HTTP 客户端收到 401／421。 401：令牌错误或缺失（opendeck-mcp token）。421：客户端使用了服务器不认识的主机名；请使用 --allowed-host 添加该主机名。服务器日志位于其数据文件夹中的 http.log。

开发

git clone https://github.com/kastro5/opendeck-mcp && cd opendeck-mcp
uv sync
uv run pytest                 # unit tests, against a scrubbed fixture config
uv run pytest -m live         # also check snapshots against your real OpenDeck install (read-only)
claude mcp add opendeck-dev -- uv --directory /path/to/opendeck-mcp run opendeck-mcp

测试夹具是真实的 OpenDeck 配置文件，其中每个设置值都已替换（scripts/scrub_fixture.py），另附精简过的插件清单和空图标文件。

许可证

MIT。与 OpenDeck 或 Elgato 无关联。

图标和字体在运行时下载，不随软件捆绑： Material Design Icons（Apache 2.0）、 Simple Icons（CC0；品牌徽标仍为其所有者的商标）、 Twemoji（图形采用 CC-BY 4.0 许可，© Twitter/X 及贡献者），以及 OpenDeck 标题字体，来自 Google Fonts（OFL）。