OpenDeck

opendeck-mcp

AI エージェントに頼んで、OpenDeck のストリームコントローラーを設定できます。

「左上のキーに、マイクをミュートして Discord を開く Multi Action を設定して、デフォルトのプロファイルから『Gaming』プロファイルを作成し、Steam がフォーカスされたらそのプロファイルに切り替えてください。」

opendeck-mcp は MCP サーバーです。Claude Code（または任意の MCP クライアント）がデッキ、プロファイル、プラグインを読み取り、変更をステージングして差分を表示した後に適用できます。バックアップも作成されるため、変更を元に戻せます。Elgato Stream Decks や、Ulanzi D200H/D200X などプラグインが提供するデバイスを含め、OpenDeck が制御するあらゆるデバイスで動作します。

目次

• できること
• インストール
  • アップグレード
  • その他の MCP クライアント
  • 別のコンピューターから使用する
  • OpenDeck プラグインとして使用する
• 使い方
• 仕組み
• 安全性
• ツール
• 制限事項
• トラブルシューティング
• 開発

できること

• すべてを確認： デバイスのグリッドサイズ、ダイヤル、タッチポイント、プロファイル、各キーのアクション、タイトル、設定、インストール済みプラグインとそのアクションを確認できます。
• キーを編集： プロファイルやデバイスをまたいで、キー、ダイヤル、タッチポイントを配置、更新（タイトル、フォント、色、画像、設定）、クリア、移動、入れ替え、コピーできます。
• Multi Action と Toggle Action： 内部のアクションを追加・削除し、アクション間の遅延を設定できます。
• プロファイル： プロファイル（Folder/Name 形式を含む）を作成、複製、名前変更（古い名前への参照も更新）、削除でき、各デバイスの起動時に使用するプロファイルを選択できます。
• アプリ切り替え： アプリにフォーカスが当たると、デバイスのプロファイルを自動的に切り替えられます。
• プラグイン：
  • OpenDeck の Plugin Manager と同じカタログに加え、Elgato のプラグインアーカイブも検索できます。
  • プラグインをインストール、更新、削除できます。
  • 秘密情報を伏せた状態で、プラグイン設定を読み書きできます。
  • プラグインのログを確認できます。
• 即時編集： デバイスに表示中のプロファイルにあるキーのタイトル、画像、設定を変更すると、再起動なしで即座に反映されます。undo_live で変更を元に戻せます。
• アイコンとフォルダー： テキスト、絵文字、約3,400種類のブランドロゴ、約7,400種類のシンボルからキー画像を作成したり、戻るキー付きのサブプロファイルを開くフォルダーキーを作成したりできます。
• 画像： render_profile を使うと、OpenDeck が描画するデッキを表示できます。ステージング中の変更を枠で示したり、変更前と変更後を並べて表示したりできるため、適用前にレイアウトを確認できます。
• Home Assistant： 名前、エリア、ドメインでエンティティを検索し、Home Assistant プラグインに保存済みのログイン情報を使って、そのエンティティを操作するキーの設定をすぐに作成できます。
• 元に戻す： 適用のたびにバックアップが作成され、restore_backup で元の状態に戻せます。

インストール

OpenDeck 2.14、uv、Claude Code（または後述の別の MCP クライアント）が必要です。uv が適切な Python を自動で取得します。

claude mcp add opendeck --scope user -- uvx [email protected]

その後、Claude Code を再起動して、「OpenDeckには何がありますか？」のように尋ねてください。

PyPI および io.github.kastro5/opendeck-mcp として MCP Registry で公開されています。GitHub から直接実行する場合はこちらです：uvx --from git+https://github.com/kastro5/[email protected] opendeck-mcp。

OpenDeck のフォルダーは自動的に検出されます。通常とは異なる場所にある場合は、環境変数で上書きしてください（claude mcp add … -e NAME=value）。

変数	デフォルト（Windows）
OPENDECK_CONFIG_DIR	%APPDATA%\opendeck
OPENDECK_EXE	%LOCALAPPDATA%\OpenDeck\opendeck.exe
OPENDECK_LOG_DIR	%LOCALAPPDATA%\opendeck\logs
OPENDECK_MCP_DATA_DIR	%LOCALAPPDATA%\opendeck-mcp（サーバー独自のプラン、バックアップ、キャッシュ）
OPENDECK_MCP_HA_VERIFY_TLS	1。自己署名証明書を使った https 上の Home Assistant では 0 に設定します
OPENDECK_MCP_TOKEN	HTTP トークン（デフォルト：一度だけ生成。詳細は後述）

アップグレード

コマンドではバージョンが固定されているため、新しいタグで登録し直してください。

claude mcp remove opendeck --scope user
claude mcp add opendeck --scope user -- uvx [email protected]

アップグレード後の最初の適用時に、同じ再起動の中でコンパニオンブリッジプラグインも更新されます（仕組みを参照）。

その他の MCP クライアント

stdio サーバーを起動できるクライアントであれば使用できます。一般的な JSON 設定（Claude Desktop、Cursor、VS Code など）は次のとおりです。

{
  "mcpServers": {
    "opendeck": {
      "command": "uvx",
      "args": ["[email protected]"]
    }
  }
}

別のコンピューターからの接続

サーバーは OpenDeck が動作している PC 上で、ログイン済みのデスクトップセッション内で実行する必要があります。サーバーは OpenDeck を再起動し、コマンドライン経由で通信するため、サービスや SSH セッションからは動作しません。別のマシン（ノート PC や開発用 VM）から使うには、OpenDeck が動作している PC で HTTP 経由でサーバーを公開し、接続してください。接続には Tailscale などのプライベートネットワークを推奨します。また、すべてのリクエストでトークンが必要です。

OpenDeck PC（Windows）で：

uvx [email protected] install-autostart --host <tailscale-ip>
uvx [email protected] token --host <tailscale-ip>

最初のコマンドは、サーバーをウィンドウなしでログオン時に毎回起動する小さなスクリプトをスタートアップフォルダーに配置し、サーバーをすぐに起動します。2 つ目のコマンドは、別のマシンで実行するコマンドを表示します。

claude mcp add --transport http opendeck http://<tailscale-ip>:8765/mcp --header "Authorization: Bearer <token>"

• tailscale ip -4 でアドレスを確認できます。--allow-all-interfaces を追加しない限り、サーバーは 0.0.0.0（すべてのネットワーク）を拒否します。
• 名前（MagicDNS 名など）で接続するには、--allowed-host <name> を追加します。それ以外の Host ヘッダーは拒否されます。
• opendeck-mcp token --reset で新しいトークンを生成し、opendeck-mcp uninstall-autostart で自動起動を削除してサーバーを停止できます。
• Windows ファイアウォールで、そのネットワークの受信 TCP 8765 を許可する必要があります。まだ許可されていない場合は、初回に確認が表示されます。
• Linux または macOS では、systemd のユーザーサービスまたは LaunchAgent から opendeck-mcp serve --host <ip> を実行してください。

OpenDeck プラグインとして

同じサーバーは OpenDeck プラグインとしても利用でき、uv もターミナルも必要ありません。 OpenDeck が起動と停止を行い、MCP を HTTP 経由で提供します。Windows と Linux に対応しています。macOS 用はビルドされていません。

1. OpenDeck のプラグインストアに掲載されたら OpenDeck MCP をインストールするか、 最新リリースから dev.kastro5.opendeck-mcp.sdPlugin.zip をダウンロードし、展開して OpenDeck の plugins フォルダー（Windows では %APPDATA%\opendeck\plugins）に入れ、OpenDeck を再起動します。
2. OpenDeck の Plugins タブで、OpenDeck MCP の横にある歯車をクリックします。ブラウザーでページが開き、 claude mcp add … コマンド（トークンを含む）とコピー ボタンが表示されます。コマンドを実行してから、Claude Code を再起動します。

デフォルトでは、同じ PC 上のクライアント向けに 127.0.0.1:8765 で待ち受けます。別のマシンから接続するには、同じページでネットワークアドレスを選択します。できれば Tailscale のアドレスを選んでください。リスナーはすぐに再起動し、ページに新しいコマンドが表示されます。ページでは新しいトークンも発行されます。10 分後にページは閉じます。歯車をクリックすると新しいページが開きます。

uvx サーバーとの違い：

• 適用処理はヘルパーを介して行われます。 適用すると OpenDeck とプラグインが再起動するため、 apply_changes と restore_backup は短時間だけ動作するヘルパーに処理を引き渡し、すぐに戻ります。 結果は約 10 秒後、次のツール呼び出しで届きます。
• ブリッジプラグインはありません。 プラグイン自身がデバイスのジオメトリを記録します。
• opendeck-mcp serve と同じトークンとデータフォルダーを使います。同じアドレスとポートで両方を実行しないでください。 2 つ目は待ち受けできず、歯車のページと get_overview にその旨が表示されます。
• 自身を更新または削除することはできません。OpenDeck の Plugins タブから操作してください。
• Linux ビルドは CI でコンパイルおよびスモークテストされていますが、実機のデッキではまだ試されていません。
• OpenDeck の Flatpak ビルドには対応していません。適用にはサンドボックスの外から OpenDeck を再起動する必要があるため、このプラグインは適用を拒否します。
• 実行ファイルにはコード署名がないため、初回起動時にウイルス対策ソフトから確認を求められる場合があります。

使用方法

やりたいことを説明するだけです。内部では、エージェントが次の処理を行います。

1. get_overview と show_profile を呼び出し、デバイスとキーを確認します。
2. list_actions / describe_action を使って適切なアクションを探し、設定内容を確認します。
3. set_key、add_child、manage_profile などで変更をステージングします。
4. preview_changes（画像を表示する場合は render_profile も）を呼び出し、結果を表示して、ユーザーの OK を待ちます。
5. apply_changes を呼び出します。OpenDeck が数秒間再起動し、バックアップ ID が報告されます。

小さな変更では、この手順を省略します。接続中のデバイスに表示されているプロファイル上で、既存のキーのタイトル、画像、設定を変更する場合は、再起動せずに即座に反映され、undo_live で元に戻せます。タイトルのスタイル、表示状態、ほかのプロファイル、すべての構造変更は、引き続きステージングを経由します。

たとえば、*「Fusion 360 のプロフィールを作って、よく使うスケッチツールとソリッドツールのキーを配置し、残りはフォルダーに入れて、Fusion が前面にあるときはいつでもそのプロフィールに切り替えて」*と指示すると、Fusion のショートカットを送信する Simulate Input キー、make_icon で作成したアイコン、「More」フォルダー、アプリルールを備えたプロフィールが作成されます。

キーは show_profile の描画方法に沿って指定します：

     c1              c2              c3              c4              c5
r1    Multi Action    "GitHub"        Toggle Action   ·               ·
r2    ·               Entity (custo…  ·               Switch Profile  ·
r3    Device Bright…  ·               "rew"           ·               (wide →)

スロット	意味
r1c1	1 行目、1 列目
key13	生の位置 13（0 始まり）
dial1	1 つ目のダイヤル
touch1	1 つ目のタッチポイント
r1c1/child2	Multi または Toggle Action 内の 2 つ目のアクション

仕組み

OpenDeck にはレイアウトを変更する API がありません。プロファイルはメモリ上に保持され、実行中に編集されたファイルは上書きされます。そのため、opendeck-mcp は OpenDeck を停止した状態でファイルを操作します。

1. 編集内容の準備。 各編集はプラン内の操作として記録されます。この時点ではまだ何も書き込まれません。 show_profile では、準備された編集に * が付いて表示されます。
2. 適用。
   • まず、OpenDeck にメモリ上の状態を保存するよう要求します。コマンドライン経由でプロファイルの切り替えを実行し、選択したプロファイルを書き込ませます。
   • 次に、OpenDeck とそのプラグインプロセスを停止します。
   • プランを、読み直したばかりのファイルに適用します。その間に OpenDeck の UI で準備済みの内容が変更されていた場合、適用処理は競合を報告し、何も書き込みません。
   • ファイルをバックアップし、アトミックに書き込み、読み戻して再検証します。何か問題が発生した場合は、バックアップが自動的に復元されます。
   • 最後に、OpenDeck を再起動し、デタッチして非表示にします。
3. 忠実なファイル。 アクションデータは、OpenDeck とまったく同じ方法でプラグインマニフェストから再構築され、JSON は OpenDeck の形式でバイト単位まで忠実に書き込まれます。OpenDeck が読み込めないプロファイルは空のプロファイルに置き換えられるため、書き込みは毎回 2 回検証されます。
4. デバイスのジオメトリ。 OpenDeck はデバイスの行数 × 列数をどこにも保存しません。そのため、最初の適用時に小さな補助プラグイン OpenDeck MCP Bridge（アクションなし、JavaScript 約 60 行）もインストールします。このプラグインは、OpenDeck がプラグインに通知するジオメトリを専用の設定ファイルに記録し、サーバーはそこから読み取ります。サーバーと同じバージョンで管理されるため、新しいリリースでは次回の適用時に更新されます。
5. 画像。 新しいキー画像は data: URL として保存されます。OpenDeck はこれを受け付け、次回の保存時にファイルへ変換します。

即時編集

タイトルと画像は、コマンドライン（--process-message）経由で実行中の OpenDeck に送信され、setTitle および setImage イベントとして処理されます。設定は OpenDeck のローカルなプラグイン WebSocket 経由で送信し、キーの設定パネルになりすまします。これは、設定が変更されたことを OpenDeck がプラグインに通知する唯一の経路だからです。その後、OpenDeck に保存を要求し、ファイルを検査します。各編集の前に、以前のタイトル、画像（バイト列として）、設定がサーバーのデータフォルダー内の live_journal.jsonl に書き込まれます。この記録を undo_live が再生します。

安全性

• 確認するまで変更されません。 ステージングツールは OpenDeck に一切変更を加えません。apply_changes、 restore_backup、プラグインのインストールはいずれも、confirm=true を指定した 2 回目の呼び出しが必要です。
• バックアップ。 変更の適用前には毎回、profiles/、images/、applications.json と、変更対象となるその他のファイルを %LOCALAPPDATA%\opendeck-mcp\backups にコピーします。直近の 30 件のバックアップを保持します（常に最低 5 件を保持します）。 復元時も、まず現在の状態をバックアップします。バックアップには秘密情報を含むプラグイン設定が含まれるため、お使いのマシンから外部に出ることはありません。
• 秘密情報はマスキングされます。 認証情報（トークン、パスワード、API キー、JWT、Bearer 値など）に見えるものは、設定、差分、例、ログで «redacted» と表示されます。«redacted» を渡し返すと、保存済みの値が維持されます。
• リスクのあるキーには警告が表示されます。 Run Command キーはコマンドを実行し、Simulate Input キーはフォーカス中のウィンドウに入力し、Web 用ではない URI を指定した Open URL キーはプログラムを起動できます。ステージング時とプレビューで、それぞれに ⚠ が表示されます。
• プラグインはサードパーティ製のコードです。 stage_plugin はまずプラグインをダウンロードして調査します。調査対象は、作成者、バージョン、sha256、実行方法、対応プラットフォーム、カタログに記載された AI 支援 フラグです。同意した後にのみ、インストールをステージングします。組み込みプラグインは削除できません。
• Home Assistant。 Home Assistant ツールは、Home Assistant プラグインに保存されたサーバー URL とアクセストークンを再利用します。トークンはそのサーバーにのみ送信され、表示されることはありません。ha_call_service は実際のご自宅に作用するため、confirm=true を指定した 2 回目の呼び出しが必要です。
• 即時編集はバックアップされません。 変更の適用を経由しないため、代わりに変更前のタイトル、画像、設定がジャーナル（直近 200 件の編集）に保存され、undo_live で元に戻せます。
• HTTP トークンはデッキへの鍵です。 トークンを持ち、ポートに接続できる人は、キーの変更やプラグインのインストールができるほか、Run Command キーを通じてプログラムを実行できます。サーバーはプライベートアドレスで稼働させ、トークンが漏えいした場合は opendeck-mcp token --reset を実行してください。
• バージョン確認。 明示的に許可しない限り、OpenDeck のバージョンが 2.14.x 以外の場合、変更の適用は拒否されます。

ネットワークとファイル

• インターネット： プラグインカタログとプラグインのダウンロード（find_plugins、stage_plugin）、および render_profile 用のタイトルフォントと make_icon 用のアイコンセットのみです。これらはそれぞれ jsDelivr から一度取得され、キャッシュされます。それ以外の通信やテレメトリーはありません。
• ローカルネットワーク： Home Assistant ツールを使用した場合に限り、お使いの Home Assistant に接続します。
• %LOCALAPPDATA%\opendeck-mcp 内のファイル：plan.json（ステージング中の変更）、backups/、 live_journal.jsonl、icons/（make_icon で作成）、cache/（カタログ、フォント、アイコンセット）、 device_overrides.json、および HTTP 用の http_token と http.log。フォルダーを削除すると、すべてがリセットされます。

ツール

種類	ツール
読み取り	get_overview、show_profile、render_profile、list_actions、describe_action、get_plugin_settings、read_logs、get_app_rules、find_plugins、find_icons、preview_changes、list_backups
ステージング	set_key、update_key、clear_key、move_key、add_child、remove_child、set_multi_delays、make_folder、manage_profile、set_app_rule、set_plugin_settings、stage_plugin、discard_changes、set_device_layout
アイコン	make_icon（image として渡せる PNG を保存します）
適用	apply_changes、restore_backup、undo_live
Home Assistant	ha_search、ha_describe_entity、ha_call_service

制限事項

• 適用すると OpenDeck が再起動します（約 5 秒）。開いている設定パネルで未保存の編集内容は失われ、プラグインも再起動します。
• 一部の設定には例が必要です。 OpenDeck 独自のアクションと Starter Pack の設定は詳しく把握されています。その他のプラグインについては、エージェントはプラグインの設定ページにあるヒントと既存のキーをもとに処理します。それだけでは不十分な場合は、アクションを配置し、OpenDeck の UI で設定を完了してください。
• アプリルール名。 アプリルールは、フォーカス中のアプリに OpenDeck が割り当てた名前と照合します。Windows では実行ファイルの説明（例：Autodesk Fusion、Visual Studio Code）、それ以外ではファイル名が使われます。get_app_rules には、開いているアプリの正確な名前が表示されます。
• テスト済みのプラットフォーム。 Windows 11、OpenDeck 2.14.1、Ulanzi D200H、Home Assistant でテスト済みです。macOS と Linux のパスおよびプロセス処理は実装されていますが、テストされていません。
• ライブ制御には制限があります。 タイトル、画像、設定の編集は即座に反映されますが、それ以外は再起動が必要です。キーの押下やプロファイルの切り替えをライブで行うことはできません。
• 画像はおおよそ再現されますが、正確ではありません。 render_profile は、OpenDeck が保存していない限り、プラグインの実行中に描画される画像（時計や Home Assistant のライブ状態など）を認識できません。また、OpenDeck 独自の Multi/Toggle Action アイコンは、似た見た目で描画されます。
• 開いている設定パネルは更新されなくなります。 設定を即時編集した後、そのキーの設定パネルがすでに OpenDeck のウィンドウで開いている場合、再度開くまで更新されません。

トラブルシューティング

• 「OpenDeck の実行ファイルが見つかりません」／「設定フォルダーが見つかりません」：OPENDECK_EXE／OPENDECK_CONFIG_DIR を設定してください（インストールを参照）。
• 適用が拒否される：テストされていない OpenDeck バージョンです。 お使いのバージョンに対応したリリースがあるか、変更履歴を確認してください。apply_changes(allow_untested_version=true) を使うと、バックアップを作成したうえで、自己責任で制限を解除できます。
• 適用時に競合が報告される。 ステージしたキーが、その後 OpenDeck で変更されています。preview_changes を確認してから、そのキーを破棄して再度ステージするか、on_conflict="skip" を指定して適用してください。
• デバイスに「geometry unknown」と表示される。 ジオメトリーは、最初の適用時にインストールされるブリッジプラグインによって取得されます。それまでは、set_device_layout で行数と列数を手動設定できます。
• 適用を元に戻す： list_backups を実行し、その後 restore_backup を実行してください。
• プラグイン：歯車のページに「not serving」と表示される。 別のプログラムがポートを使用しています。通常は、同じアドレスで実行中の opendeck-mcp serve です。ページで別のポートを選ぶか、他のサーバーを停止してください（opendeck-mcp uninstall-autostart）。プラグインのログは、OpenDeck のログフォルダー内の logs\plugins\dev.kastro5.opendeck-mcp.sdPlugin.log にあります。
• HTTP クライアントで 401／421 が発生する。 401：トークンが間違っているか、指定されていません（opendeck-mcp token）。421：クライアントがサーバーで認識されていないホスト名を使用しています。--allowed-host を使って追加してください。サーバーのログは、データフォルダー内の http.log にあります。

開発

git clone https://github.com/kastro5/opendeck-mcp && cd opendeck-mcp
uv sync
uv run pytest                 # unit tests, against a scrubbed fixture config
uv run pytest -m live         # also check snapshots against your real OpenDeck install (read-only)
claude mcp add opendeck-dev -- uv --directory /path/to/opendeck-mcp run opendeck-mcp

テスト用フィクスチャには、すべての設定値を置き換えた実際の OpenDeck プロファイル（scripts/scrub_fixture.py）と、アイコンファイルを空にした簡略版のプラグインマニフェストを使用しています。

ライセンス

MIT。OpenDeck または Elgato とは無関係です。

アイコンとフォントは実行時にダウンロードされ、同梱されません： Material Design Icons（Apache 2.0）、 Simple Icons（CC0。ブランドロゴは引き続き各所有者の商標です）、 Twemoji（グラフィックは CC-BY 4.0、© Twitter/X および貢献者）、および OpenDeck のタイトルフォント（Google Fonts 提供、OFL）。