Streamdeck MCP

🚀 🎛️ Stream Deck MCP · v0.1.0

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

🚀 快速开始

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

📚 详细文档

可用工具

自然语言示例

• "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构建 🧡