Moonlight Desktop MCP

Moonlight Desktop MCP

ペアリング済みの Apollo または Sunshine を実行する Windows デスクトップを視覚的に操作するための、ローカル stdio MCP サーバーです。MCP クライアントやコーディングエージェントは、リモート画面をキャプチャし、表示されているコントロールを特定して、同じ座標空間でマウスまたはキーボード入力を送信できます。

サーバーは操作側の macOS、Linux、または Windows マシン上で動作し、Moonlight/GameStream を介して Windows ホストと通信します。アプリケーションを開く、設定を変更する、ダイアログを閉じるといった画面上で見える操作を対象としており、Windows の非表示シェル、レジストリ、プロセスへのアクセスや、Windows 側のエージェントには対応していません。

利用目的に応じた開始方法

目的	こちらから開始
MCP のインストール、更新、実行	インストールと更新
PC をペアリングして視覚操作ツールを使う	MCP の使用
ソースを自分でクローン、変更、テスト、ビルドする	ソースからの開発
エージェントに簡潔な操作上の契約を提示する	エージェント操作ガイド

ほとんどの方は最初の 2 つのリンクだけで十分です。開発ガイドに記載されているコマンドは、通常のインストール手順には含まれません。

クライアントとエージェント向けの情報

• server.json には、カタログやクライアント向けの標準的な MCP サーバー ID、リポジトリ、バージョン、正式なインストールページが記載されています。このプロジェクトにはコントローラー向けのネイティブビルドが必要なため、npm パッケージやホスト型リモートエンドポイントではなく、管理対象インストーラーを案内しています。
• llms.txt は、正式なインストール、使用方法、ツール、アーキテクチャ、安全性に関するドキュメントを簡潔にまとめた、モデルが読み取りやすい案内です。
• AGENTS.md は、このリポジトリで作業するコーディングエージェント向けのガイドです。 docs/AGENT-GUIDE.md は、インストール済み MCP を操作するエージェント向けのガイドです。Codex ユーザーは、同梱の moonlight-desktop-operator スキルもインストールできます。

インストールまたは更新

MCP を実行するコンピューター（操作対象の Windows PC ではなく、お使いの Mac、Linux、または Windows マシン）で、次のコマンドを 1 つ実行してください。クリーンなインストール環境を更新する場合は、後で同じコマンドを再実行します。

このプロジェクトは、そのまま実行できる npm パッケージや npx パッケージとしては配布されていません。以下のプラットフォーム用インストーラーを使用すると、ネイティブ Moonlight ブリッジとコントローラーの依存関係がまとめてビルドされ、確認されます。

macOS と Linux：

curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/edulelis/moonlight-desktop-mcp/main/install.sh | bash

Windows PowerShell：

irm https://raw.githubusercontent.com/edulelis/moonlight-desktop-mcp/main/install.ps1 | iex

インストーラーはコントローラー側のビルド依存関係を取得し、独自のチェックアウトを作成または更新して、ネイティブ Moonlight ブリッジをビルドし、準備状況を確認します。ペアリングデータはチェックアウトの外部に保持されます。Codex CLI がすでに利用可能な場合は、moonlight-desktop MCP エントリが存在しないときに追加します。Windows ホストには何もインストールしません。Windows ホストでは、Desktop アプリケーションを含む Apollo または Sunshine がすでに実行されている必要があります。確認方法、バージョンの固定、その他の MCP クライアントについては、インストールと更新を参照してください。

MCP の使用

通常のコンピューター操作の流れは次のとおりです。

1. 最初に一度だけペアリングします：host_status → pairing_begin → 返された PIN を返された Apollo URL で入力 → pairing_status。
2. PC がスリープ中または電源オフの可能性がある場合は、必要に応じて profile_wol_configure で Wake-on-LAN を設定します。
3. 各タスクの前に desktop_channel_status を呼び出し、その nextAction に従ってから、トランスポートが利用可能で起動準備が進行中でない場合に session_preflight と session_start を呼び出します。
4. Desktop をキャプチャし、現在のフレームで、要求されたアプリまたはセットアップ状態が画面上で利用可能かどうかを確認してから、対象を特定し、そのフレームの座標空間で入力して、再度キャプチャして結果を検証します。
5. 完了したら session_stop を呼び出します。

session_start は常に Desktop を開きます。Apollo に登録されていないアプリケーションも、Desktop またはスタートメニューから起動できます。provider_app_start は、ユーザーが Apollo に登録されたプロバイダーアプリの起動を明示的に求めた場合にのみ使用してください。詳細なセットアップ、安全上の制約、例については、MCP の使用をご覧ください。

提供機能

必要な操作	MCP ツール
ホストのペアリング、確認、起動	host_status、ペアリングツール、profile_status、profile_wol_configure、host_wake
Desktop の確認／起動／停止	session_preflight、session_start、session_status、session_stop
リモート画面の表示	screen_capture、OCR、テキスト／テンプレート検索、切り抜き、差分、待機
操作と確認	マウス、ドラッグ、スクロール、テキスト、名前付きキー／ホットキーツール、視覚的な待機

ツールの完全な仕様はdocs/TOOLS.mdをご覧ください。同梱のエージェント向けガイダンスはdocs/AGENT-GUIDE.mdにあります。

対象範囲と安全性

• Desktop ストリームは一度に 1 つだけです。別の GameStream クライアントがチャネルを使用中の場合、MCP はその状態を報告し、引き継ぎません。
• リモートアプリの利用可否、インストーラーの進行状況、アカウントの状態、ライセンスの状態は、現在描画されている Desktop 上でのみ確認します。リモートシェル、レジストリ、プロセスの調査は行いません。
• ペアリングキー、フレーム、OCR キャッシュ、Wake-on-LAN 設定は、制御するマシン内に保持されます。
• H.264 Desktop ビデオのデフォルトは 1920×1080／30fps、20 Mbps です。接続が遅い場合は、session_start に stream_profile: "low_bandwidth" を渡すと、1280×720／30fps、8 Mbps になります。幅、高さ、FPS、ビットレートは、セッションごとの上書き設定として任意で指定できます。音声、クリップボード、ファイル転送、HEVC／AV1、セッションの復旧は対象外です。
• 重要な操作はすべて、新しいキャプチャを使って視覚的に検証してください。

互換性、トラブルシューティング、アーキテクチャ、セキュリティの詳細については、docs/COMPATIBILITY.md、docs/TROUBLESHOOTING.md、docs/ARCHITECTURE.md、docs/SECURITY.mdをご覧ください。