streamdeck-mcp

Stream Deck MCP

Stream Deck MCP 让 Agent 能够构建和重新配置真正的 Elgato Stream Deck 配置文件。

快速开始 · 演示 · 功能 · 工具 · 开发

告诉你的 AI 想要什么样的 Stream Deck。你会得到一份精心设计的配置文件，其中包含按钮、图标、颜色、旋钮、触控条图案，以及配套的 shell 脚本。Stream Deck MCP 会写入 Elgato 桌面应用所使用的同一种配置文件格式，因此 Agent 无需你先构建 Stream Deck 插件，就能创建真正可用的本地操作面板。

它适用于 Claude Desktop、Claude Code、Cursor、Codex，以及任何能够启动 stdio 服务的 MCP 客户端。

快速开始

Claude Code：

claude mcp add streamdeck -- uvx streamdeck-mcp

Claude Desktop、Cursor、Codex 和其他 MCP 客户端可以使用同一条命令：

{
  "mcpServers": {
    "streamdeck": {
      "command": "uvx",
      "args": ["streamdeck-mcp"]
    }
  }
}

然后让你的 Agent 创建操作面板：

为我的 Stream Deck + XL 制作一个 Slack 控制面板。

在 Claude Code 中，安装随附的设计器技能，以获得更好的布局、配色、硬件和插件操作指导：

uvx --from streamdeck-mcp streamdeck-mcp-install-skill

演示

_{使用 Remotion 生成的产品预告片，展示硬件清单、插件发现、已配置操作的复用，以及最终呈现的 Stream Deck + XL。}

功能

• 原生配置文件创建 - 直接读取和写入 Elgato ProfilesV3 文件；旧版安装则回退使用 ProfilesV2。
• 硬件清单 - 写入前发现配置文件页面、设备型号名称、按键布局、旋钮和触控条支持情况。
• 已配置操作搜索 - streamdeck_find_actions 会扫描现有配置文件和页面，查找可直接粘贴的插件按钮和旋钮（包括在应用中配置的受保护 Elgato 第一方插件）。
• 已安装插件发现 - 使用 streamdeck_read_plugins 扫描可读取的 Stream Deck 插件清单，让 Agent 在合成新操作时能找到插件和操作的 UUID。
• 已配置插件操作复用 - 优先通过 find_actions 或 streamdeck_read_page 的 button.raw 复制现有操作，以保留私有的属性检查器设置。
• 离线图标生成 - 使用约 7,400 个内置 Material Design Icons，或简短的文本标签，生成按钮和触控条 PNG 图像。
• 脚本驱动的自动化 - 在 ~/StreamDeckScripts/ 中创建可执行 shell 脚本，并在没有合适插件操作时，将其关联到 Stream Deck 的 Open 操作。
• 旋钮和触控条支持 - 必要时安装内置的精简版 Stream Deck 插件，确保编码器图像在应用重启后仍能保留。
• 安全写入流程 - 强制执行退出应用、写入、重新启动的工作流，防止 Elgato 应用覆盖清单编辑。

Agent 工作流

重点不是通用按钮。优先复用用户已在 Stream Deck 应用中配置的操作（Hue、OBS、Home Assistant、Spotify 插件等），然后将它们组合到主题页面中。当 Agent 也加载了 Slack、Home Assistant、OBS、GitHub、Hue、Spotify 或其他 MCP 服务时，它可以查询这些系统，挑选合适的实体；如果有原生插件操作可用，仍通过这些操作配置控制面板，只有在需要时才回退到脚本。

试试以下提示词：

• “给我做一个 Slack 控制面板。” 查询频道、状态和未读状态；创建频道跳转、状态切换、全部标为已读的控件和旋钮。
• “为客厅做一个 Hello Kitty 主题的 Home Assistant 仪表板。” 使用 streamdeck_find_actions 查找现有的 HA 插件按钮，然后按匹配的视觉风格进行布局；如果尚未配置任何内容，也可以通过 MCP 发现客厅实体并合成操作／编写脚本。
• “根据我实际使用的场景和音频输入制作 OBS 控制面板。” 如果已配置 OBS 插件操作，则复用它们；否则读取场景／来源，并编写场景切换、来源开关和各输入的旋钮控制。
• “用北欧配色为这个代码仓库做一个开发者控制面板。” 读取项目脚本和 GitHub 上下文；创建本地命令按钮、PR 链接和 CI 快捷操作。
• “做一个周五演示用的控制面板。” 先查找已配置的插件操作，再用本地脚本补足缺失项，以此组合 Zoom、Slack、Hue 和屏幕录制功能。

迭代成本很低：更改提示词，重新运行创作流程，即可获得新配置文件。

安装

打包后的入口点为 streamdeck-mcp，通过 uvx 运行。

Cursor

也可以粘贴到 ~/.cursor/mcp.json 中：

{
  "mcpServers": {
    "streamdeck": {
      "command": "uvx",
      "args": ["streamdeck-mcp"]
    }
  }
}

Claude Desktop

在 macOS 上粘贴到 ~/Library/Application Support/Claude/claude_desktop_config.json，或在 Windows 上粘贴到 %APPDATA%\Claude\claude_desktop_config.json，然后重启 Claude Desktop：

{
  "mcpServers": {
    "streamdeck": {
      "command": "uvx",
      "args": ["streamdeck-mcp"]
    }
  }
}

Claude Code

claude mcp add streamdeck -- uvx streamdeck-mcp

OpenAI Codex

添加到 ~/.codex/config.toml：

[mcp_servers.streamdeck]
command = "uvx"
args = ["streamdeck-mcp"]

其他 MCP 客户端

任何支持通过 stdio 使用 MCP 的客户端都能以相同方式工作：将其指向 uvx streamdeck-mcp。

Linux 和无头环境

默认配置文件写入器面向 Elgato Stream Deck 桌面应用，该应用可在 macOS 和 Windows 上使用。在 Linux、无头机器，或希望由 MCP 服务直接控制硬件的环境中，请使用旧版 USB 服务：

uvx --from streamdeck-mcp streamdeck-mcp-usb

客户端配置格式：

{
  "mcpServers": {
    "streamdeck": {
      "command": "uvx",
      "args": ["--from", "streamdeck-mcp", "streamdeck-mcp-usb"]
    }
  }
}

工具

工具	功能
streamdeck_find_actions	搜索各配置文件中的按钮和拨轮，并返回可直接粘贴到 streamdeck_write_page 的原生 action 对象。
streamdeck_read_plugins	列出已安装的 Stream Deck 插件，以及可读取的插件清单中声明的操作。对于受保护或二进制清单，会报告诊断信息，而不会导致整个目录读取失败。
streamdeck_read_profiles	列出 ProfilesV3 或 ProfilesV2 中的桌面配置文件、设备元数据、页面目录和活动配置文件根目录。
streamdeck_read_page	读取页面清单，并返回简化的按钮详情和原始原生操作对象。
streamdeck_write_page	创建或重写页面清单。复用已配置的第三方插件操作时，优先使用 find_actions 返回的 action 或 button.raw。
streamdeck_create_icon	根据 Material Design 图标或文本生成按钮或触控条 PNG。图标已离线打包；遇到未知名称时，会提供相似名称建议。
streamdeck_create_action	在 ~/StreamDeckScripts/ 中创建可执行 shell 脚本，并返回一个 Open 操作块。
streamdeck_restart_app	在修改配置文件后重启 macOS Stream Deck 桌面应用。
streamdeck_install_mcp_plugin	安装随附的 streamdeck-mcp Stream Deck 插件，用于持久显示编码器图像。通常由 streamdeck_write_page 自动安装。

提示词支持：

提示词	功能
design_streamdeck_deck	在用户描述想要的控制台之前，为不具备技能感知能力的 MCP 客户端提供精简的控制台设计简报。

streamdeck-designer Skill

Stream Deck MCP 附带一项适用于 Claude Code 的 Agent Skill，指导 Agent 从头到尾规划、设计主题并创作完整的控制台。

使用以下命令安装：

uvx --from streamdeck-mcp streamdeck-mcp-install-skill

该技能会复制到 ~/.claude/skills/streamdeck-designer/。安装后请重启 Claude Code 或启动新会话。更新软件包后，重新运行并添加 --force 以升级。

该技能涵盖：

• 硬件清单和特定型号的布局规划。
• 主题调色板、字体策略和图标配色建议。
• 为 Stream Deck + 和 + XL 设备创作拨轮和触控条内容。
• Hue、OBS、Spotify、Home Assistant、Twitch、shell 命令和浏览器工作流的集成方案。
• 通过 streamdeck_find_actions 和 streamdeck_read_page / button.raw 复用现有插件操作。

不会加载 Claude Code 技能的客户端可以改为调用 design_streamdeck_deck MCP 提示词。

开发

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 .

若要根据共享的 Very Good Plugins MCP 标准审核此仓库：

../mcp-ecosystem/scripts/audit-server.sh .

编写说明

• 如果存在 ProfilesV3，优先使用它。仍支持 ProfilesV2，但应通过 directory_id 或 page_index 定位现有页面，因为 Elgato 在此版本中使用不透明的目录名称。
• Elgato 桌面应用会将配置文件保留在内存中，并可能在退出时覆盖磁盘上的清单编辑内容。如果应用正在运行且未设置 auto_quit_app，streamdeck_write_page 会引发 StreamDeckAppRunningError。
• 在 macOS 上，传入 auto_quit_app: true 可在写入前退出应用，完成后再调用 streamdeck_restart_app。在 Windows 上，请手动退出并重新启动 Elgato 应用。
• 如果 Elgato 应用未安装在 /Applications/Elgato Stream Deck.app，请设置 STREAMDECK_APP_PATH。
• 生成的图标位于 ~/.streamdeck-mcp/generated-icons/。生成的 shell 脚本位于 ~/StreamDeckScripts/。

传统 USB 模式

原始的 USB 直连服务仍可使用，以保持向后兼容。它提供直接控制硬件的工具：

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。

连接了多个设备时，请先调用 streamdeck_list_devices，然后将所需设备的 serial 传递给 streamdeck_connect。省略 serial 将保留传统行为，即打开枚举到的第一台设备。

运行方式：

uvx --from streamdeck-mcp streamdeck-mcp-usb

支持

• 在 GitHub 上提交问题
• 联系 Very Good Plugins

由 Very Good Plugins 构建。