streamdeck-mcp

Stream Deck MCP

Stream Deck MCP を使うと、エージェントが実際の Elgato Stream Deck プロファイルを作成、再構成できます。

クイックスタート · デモ · 機能 · ツール · 開発

使いたい Stream Deck を AI に伝えるだけで、ボタン、アイコン、色、ダイヤル、タッチストリップの画像と、その裏側で動作するシェルスクリプトを備えた洗練されたプロファイルが完成します。Stream Deck MCP は Elgato デスクトップアプリがすでに使用しているものと同じプロファイル形式を書き込むため、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"]
    }
  }
}

次に、エージェントにデッキを依頼します：

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 プラグインのマニフェストをスキャンし、新しいアクションを生成する際にエージェントがプラグインとアクションの UUID を見つけられるようにします。
• 設定済みプラグインアクションの再利用 - 既存アクションを find_actions または streamdeck_read_page の button.raw 経由でコピーする方法を優先し、非公開の Property Inspector 設定を保持します。
• オフラインでのアイコン生成 - 同梱の約 7,400 個の Material Design Icons、または短いテキストラベルから、ボタンやタッチストリップ用の PNG をレンダリングします。
• スクリプトを使った自動化 - プラグインアクションが適さない場合、~/StreamDeckScripts/ に実行可能なシェルスクリプトを作成し、Stream Deck の Open アクションに関連付けます。
• ダイヤルとタッチストリップへの対応 - 必要に応じて最小構成の Stream Deck プラグインをインストールし、アプリの再起動後もエンコーダーの画像が保持されるようにします。
• 安全な書き込みサイクル - Elgato アプリによるマニフェスト編集の上書きを防ぐため、終了、書き込み、再起動のワークフローを徹底します。

エージェント型ワークフロー

汎用的なボタンを作ることが目的ではありません。まず、ユーザーが Stream Deck アプリで設定済みのアクション（Hue、OBS、Home Assistant、Spotify のプラグインなど）を再利用し、それらをテーマに沿ったページにまとめることを優先してください。エージェントに Slack、Home Assistant、OBS、GitHub、Hue、Spotify などの MCP サーバーも読み込まれていれば、対象システムに問い合わせて適切なエンティティを選び、利用可能な場合はネイティブプラグインのアクションを通じてデッキを設定できます。必要な場合に限り、スクリプトに切り替えます。

次のようなプロンプトを試してください。

• 「Slack 用のコントロールボードを作って。」 チャンネル、ステータス、未読状態を確認し、チャンネルへの移動、ステータスの切り替え、すべて既読にする操作、ダイヤルを作成します。
• 「リビングルーム用のハローキティをテーマにした 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 およびヘッドレス環境

デフォルトのプロファイルライターは、macOS と Windows で利用できる Elgato Stream Deck デスクトップアプリを対象としています。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 Icons またはテキストから、ボタン用またはタッチストリップ用の PNG を生成します。アイコンはオフラインで使用できるよう同梱されており、不明な名前には類似候補が提示されます。
streamdeck_create_action	~/StreamDeckScripts/ に実行可能なシェルスクリプトを作成し、Open アクションブロックを返します。
streamdeck_restart_app	プロファイルの変更後に macOS の Stream Deck デスクトップアプリを再起動します。
streamdeck_install_mcp_plugin	エンコーダー画像を永続的に表示するための、同梱の streamdeck-mcp Stream Deck プラグインをインストールします。通常は streamdeck_write_page によって自動的にインストールされます。

プロンプトのサポート：

プロンプト	機能
design_streamdeck_deck	ユーザーが作成したいデッキについて説明する前に、スキルを認識しない MCP クライアントに、簡潔なデッキ設計の概要を提供します。

streamdeck-designer スキル

Stream Deck MCP には、デッキの計画、テーマ設定、作成を最初から最後までエージェントに教える、Claude Code 用の Agent Skill が付属しています。

次のコマンドでインストールします。

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

スキルは ~/.claude/skills/streamdeck-designer/ にコピーされます。インストール後、Claude Code を再起動するか、新しいセッションを開始してください。パッケージの更新後にアップグレードするには、--force を指定して再実行します。

このスキルでは、次の内容を扱います。

• ハードウェアの一覧確認と、モデルに応じたレイアウト計画。
• テーマの配色、タイポグラフィの方針、アイコンの色に関する指針。
• Stream Deck + および + XL デバイス向けのダイヤルとタッチストリップの作成。
• Hue、OBS、Spotify、Home Assistant、Twitch、シェルコマンド、ブラウザーのワークフローとの連携レシピ。
• 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 も引き続きサポートされていますが、Elgato はそこで不透明なディレクトリ名を使用するため、既存のページは directory_id または page_index で指定してください。
• 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/ に保存されます。生成されたシェルスクリプトは ~/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 が開発しました。