Streamdeck MCP

🚀 🎛️ Stream Deck MCP · v0.1.0

AIにStream Deckの設定をデザインさせましょう — あなたが望むことを平易な英語で記述します。AIがそれを構築します。

📌 問題の所在

Stream Deckは強力ですが、設定は面倒です。GUIをクリックしてアイコンを探し、マルチページのワークフローを設定するのには、永遠に時間がかかります。

💡 解決策

AIにあなたの希望を伝えましょう。

「録音、編集、公開用のページを持つポッドキャストスタジオのレイアウトをデザインして。
マイクミュート、録音の開始/停止、効果音、シーン切り替え用のボタンを含めること。」

AIが戦略を設計し、ページを作成し、すべてのボタンを設定します。完了です。

✨ できること

🎙️ 「ポッドキャスト用にStream Deckを設定して」 — AIがマルチページシステムを設計します。 🏠 「ホームオートメーション用のページを作成して」 — 照明、シーン、空調用のボタンが用意されます。 🎮 「Discord、OBS、Spotifyを含むゲーミングプロファイルを構築して」 — 1つのプロンプトで完全な設定が完了します。 🔄 「レイアウトをより直感的に再設計して」 — AIがワークフローを理解し、改善案を提案します。

対応機種: Stream Deck、Stream Deck Mini、Stream Deck XL、Stream Deck MK.2、Stream Deck +

⚠️ 重要: 最初にElgatoソフトウェアを終了する

このMCPサーバーは排他的なUSBアクセスを必要とします。 使用する前に、Elgato Stream Deckソフトウェアを終了する必要があります。

# macOS — Elgatoソフトウェアを終了する
killall "Stream Deck" 2>/dev/null || true

Stream Deckは一度に1つのアプリケーションからのみ制御できます。このMCPサーバーを使用している間は、Elgatoソフトウェアを実行できません（逆もまた同じです）。

🚀 クイックスタート — 2分でボタンを設定

1️⃣ 前提条件

# macOS
brew install hidapi

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

# Linux udevルール (非ルートユーザーでのアクセスに必要)
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 Desktopに追加

~/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

以上です！🎉

💻 使用例

基本的な使用法

# 以下のようにClaudeに指示を与えることで、Stream Deckの設定を行うことができます。
"Connect to my Stream Deck and show me the layout"

高度な使用法

# 以下のような高度なシナリオでも使用できます。
"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"

📚 ドキュメント

🛠️ 利用可能なツール

自然言語の例

Claudeにあなたの希望を伝えるだけです。

• "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]

🏠 Home Assistant統合

ボタンを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

アクションフィールドは任意のシェルコマンドを受け付けます。curlを使用してHome AssistantのウェブフックやHome Assistant CLIを呼び出すことができます。

🎨 カスタムアイコン

PNG/JPGファイルを任意の場所に配置し、以下のように参照することができます。

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

画像は自動的にボタンのサイズ（デッキモデルに応じて72×72または96×96）にスケーリングされます。

📁 状態保存

設定は~/.streamdeck-mcp/に保存されます。

• pages.json — ページごとのボタンの外観
• buttons.json — ページごとのボタンのアクション

🔧 技術詳細

⚠️ トラブルシューティング

"No Stream Deck found"

• USB接続を確認してください。
• Linuxの場合: udevルールを追加して再読み込みしましたか？
• macOSの場合: システム環境設定 → セキュリティとプライバシーでターミナルにUSBアクセスを許可してください。

"streamdeck library not installed"

uv pip install streamdeck pillow

ボタンが押されても反応しない場合

• 物理ボタンのコールバックには、MCPサーバーが実行中である必要があります。
• サーバーはClaude Desktopが開いている間実行されます。

"Deck disconnected"エラー

• サーバーはUSBの切断を適切に処理します。
• 再接続するには、再度 "Connect to my Stream Deck" と言ってください。

🧪 開発

# セットアップ
uv venv && uv pip install -e ".[dev]"

# サーバーを実行
uv run server.py

# テストを実行 (ハードウェア不要)
uv run pytest tests/ -v

# リント
uv run ruff check .

🔮 ロードマップ

• [ ] Home Assistantエンティティブラウザーの統合
• [ ] 絵文字からのアイコン生成
• [ ] ボタン押下時のウェブフック
• [ ] マルチデッキサポート

📄 ライセンス

MIT — ハードウェア制御は無料であるべきだからです。

Built by Jack Arturo at Very Good Plugins 🧡