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構建 🧡