shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

streamdeck-mcp

Stream Deck MCP是一个让AI通过自然语言描述来设计和配置Elgato Stream Deck布局的工具。用户只需用英语描述需求，AI即可自动创建页面、设置按钮（包括文本、图标、颜色和操作），支持多页面工作流、家庭自动化、游戏配置等场景。使用前需关闭Elgato官方软件以获取USB独占访问权限。

article

README

🚀 🎛️ Stream Deck MCP · v0.1.0

让AI为你的Stream Deck进行布局设计 — 用简洁的英语描述你的需求，AI将为你完成设置。

License: MIT

🚀 快速开始

1️⃣ 前提条件

# macOS
brew install hidapi

# Linux (Debian/Ubuntu)
sudo apt install libhidapi-libusb0

# Linux udev规则（非root用户访问需要）
sudo tee /etc/udev/rules.d/10-streamdeck.rules << EOF
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0fd9", GROUP="users", MODE="0666"
EOF
sudo udevadm control --reload-rules

2️⃣ 安装

git clone https://github.com/verygoodplugins/streamdeck-mcp.git
cd streamdeck-mcp
uv venv && uv pip install -e .

3️⃣ 添加到Claude桌面端

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "streamdeck": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/streamdeck-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

4️⃣ 使用

在Claude中输入：

Connect to my Stream Deck

然后输入：

Set button 0 to "Lights" with a blue background
Set button 1 to "Music" with action "open -a Spotify"
Create a page called "gaming" and switch to it

大功告成！🎉

✨ 主要特性

解决的问题

Stream Deck功能强大，但配置过程繁琐。通过图形用户界面（GUI）进行点击操作、查找图标以及设置多页面工作流程，这些操作十分耗时。

解决方案

只需告诉AI你想要的内容，例如：

"Design a podcast studio layout with pages for recording, editing, and publishing.
Include buttons for mic mute, recording start/stop, sound effects, and scene switching."

AI将设计布局策略、创建页面并配置每个按钮，轻松完成设置。

具体功能

🎙️ "Set up my Stream Deck for podcasting" — AI设计多页面系统 🏠 "Create a home automation page" — 包含灯光、场景、气候控制的按钮 🎮 "Build a gaming profile with Discord, OBS, and Spotify" — 一个指令完成完整设置 🔄 "Redesign my layout to be more intuitive" — AI理解工作流程并提供改进建议

支持设备：Stream Deck、Stream Deck Mini、Stream Deck XL、Stream Deck MK.2、Stream Deck +

📦 安装指南

安装依赖

# macOS
brew install hidapi

# Linux (Debian/Ubuntu)
sudo apt install libhidapi-libusb0

# Linux udev规则（非root用户访问需要）
sudo tee /etc/udev/rules.d/10-streamdeck.rules << EOF
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0fd9", GROUP="users", MODE="0666"
EOF
sudo udevadm control --reload-rules

克隆仓库并安装

git clone https://github.com/verygoodplugins/streamdeck-mcp.git
cd streamdeck-mcp
uv venv && uv pip install -e .

配置Claude桌面端

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "streamdeck": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/streamdeck-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

💻 使用示例

基础用法

在Claude中输入以下指令：

Connect to my Stream Deck

然后可以进行各种设置，例如：

Set button 0 to "Lights" with a blue background
Set button 1 to "Music" with action "open -a Spotify"
Create a page called "gaming" and switch to it

高级用法

与Home Assistant集成

Set up my Stream Deck for home control:
- Button 0: "Office Lights" that toggles light.office_ceiling
- Button 1: "All Off" that runs a scene
- Button 4: Page switch to "media" page

使用自定义图标

Set button 5 with image ~/icons/spotify.png

📚 详细文档

可用工具

| 属性 | 详情 | |------|------| | streamdeck_connect | 连接到第一个可用的设备 | | streamdeck_info | 获取设备型号、按键数量、当前页面 | | streamdeck_set_button | 设置文本、图像、颜色和操作 | | streamdeck_clear_button | 清除单个按键 | | streamdeck_set_brightness | 设置亮度（0 - 100%） | | streamdeck_create_page | 创建新的按键配置文件 | | streamdeck_switch_page | 切换活动页面 | | streamdeck_list_pages | 列出所有页面 | | streamdeck_delete_page | 删除页面（除“main”页面外） | | streamdeck_disconnect | 优雅地断开连接 |

自然语言示例

  • "Connect to my Stream Deck and show me the layout"
  • "Set button 0 to say 'Lights' with a blue background"
  • "Make button 4 open Spotify when I press it"
  • "Create a 'gaming' page with Discord, Steam, and OBS buttons"
  • "Switch to the gaming page"
  • "Set brightness to 50%"

按键布局

Stream Deck（15个按键，5×3）

[0]  [1]  [2]  [3]  [4]
[5]  [6]  [7]  [8]  [9]
[10] [11] [12] [13] [14]

Stream Deck Mini（6个按键，3×2）

[0]  [1]  [2]
[3]  [4]  [5]

Stream Deck XL（32个按键，8×4）

[0]  [1]  [2]  [3]  [4]  [5]  [6]  [7]
[8]  [9]  [10] [11] [12] [13] [14] [15]
[16] [17] [18] [19] [20] [21] [22] [23]
[24] [25] [26] [27] [28] [29] [30] [31]

状态存储

配置信息保存在 ~/.streamdeck-mcp/ 目录下：

  • pages.json — 每个页面的按键外观
  • buttons.json — 每个页面的按键操作

🔧 技术细节

开发环境设置

# 环境搭建
uv venv && uv pip install -e ".[dev]"

# 运行服务器
uv run server.py

# 运行测试（无需硬件）
uv run pytest tests/ -v

# 代码检查
uv run ruff check .

路线图

  • [ ] 集成Home Assistant实体浏览器
  • [ ] 从表情符号生成图标
  • [ ] 按键按下时触发Webhook
  • [ ] 支持多设备

⚠️ 重要提示

⚠️ 重要提示

此MCP服务器需要独占USB访问权限。在使用前，你必须退出Elgato Stream Deck软件：

# macOS — 退出Elgato软件
killall "Stream Deck" 2>/dev/null || true

Stream Deck一次只能由一个应用程序控制。使用此MCP服务器时，Elgato软件不能运行（反之亦然）。

⚠️ 故障排除

"No Stream Deck found"

  • 检查USB连接
  • 在Linux上：是否添加了udev规则并重新加载？
  • 在macOS上：在系统偏好设置 → 安全与隐私中授予终端USB访问权限

"streamdeck library not installed"

uv pip install streamdeck pillow

按键无响应

  • 物理按键回调需要MCP服务器保持运行
  • 服务器在Claude桌面端打开时运行

"Deck disconnected" 错误

  • 服务器可以优雅地处理USB断开连接
  • 只需再次输入 "Connect to my Stream Deck" 即可重新连接

📄 许可证

本项目采用MIT许可证 — 因为硬件控制应该是免费的。

由 Jack Arturo 在Very Good Plugins构建 🧡

X (Twitter)

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client