SSyncDev

Moonlight Desktop MCP Server

Lets an agent see and operate a remote Windows desktop over a Moonlight/GameStream stream from Apollo or Sunshine.

Local server

What is the Moonlight Desktop MCP Server?

Picture a Windows PC under your desk that already streams its desktop through Apollo or Sunshine. You work on a Mac or Linux laptop. The Moonlight Desktop MCP server lets your coding agent watch that stream and drive it, the way you would with a game controller app, only with mouse and keyboard events placed in the same coordinates as the captured frame.

Scope, deliberately narrow

This is visual computer use and nothing more. The agent sees what is rendered on the Windows Desktop and acts on it: opening an app, flipping a setting, closing a dialog. It has no shell on the remote machine, no registry access and no process list. Whether an installer finished or a licence is active is judged only from what is visible on screen. Some practical boundaries:

  • One desktop stream at a time; if another client holds the channel, the server says so and does not take over
  • Video defaults to 1920×1080 at 30 fps and 20 Mbps, with a low-bandwidth profile of 1280×720 at 8 Mbps
  • Audio, clipboard, file transfer and session recovery are not supported
  • Pairing keys, captured frames, OCR cache and Wake-on-LAN settings stay on the controlling machine

How a session runs

Pairing happens once. The agent calls host_status, then pairing_begin, which returns a PIN and the Apollo address to enter it at; pairing_status confirms. If the PC may be asleep, profile_wol_configure sets up Wake-on-LAN and host_wake uses it.

Each task then follows a fixed rhythm. Check desktop_channel_status and follow the next action it suggests, run session_preflight, then session_start, which always opens the Desktop. Capture with screen_capture, locate the target, send input, capture again to confirm. Finish with session_stop. provider_app_start exists for launching apps registered in Apollo, but only when you explicitly want that.

Why verification matters

Every meaningful action is supposed to be checked against a fresh capture. That keeps the agent honest about what really happened on a machine it cannot otherwise inspect.

Installation notes

The Moonlight Desktop MCP server has no npm or npx package. A platform installer for macOS, Linux or Windows PowerShell builds a native Moonlight bridge and checks controller dependencies; rerun it to update. When the Codex CLI is present it registers itself there. Other clients are configured by hand using the separate install guide. Nothing is installed on the Windows host, which must already run Apollo or Sunshine with a Desktop app.

For automation on the local machine instead, see Windows Desktop Automation or the broader terminal and desktop category, alongside other developer tools.

Recorded tools

Check the linked publisher documentation and your connected client's tool list. Names and availability can vary with the server version and account permissions.

ToolWhat it does
host_statusInspect the configured Windows host before pairing or a session.
pairing_beginStart pairing and return a PIN plus the Apollo URL where it is entered.
pairing_statusConfirm whether pairing has completed.
profile_statusShow the stored host profile.
profile_wol_configureConfigure Wake-on-LAN for a PC that may be asleep or off.
host_wakeWake the host using the configured Wake-on-LAN settings.
desktop_channel_statusCheck whether the desktop stream is available and return the suggested next action.
session_preflightRun checks before starting a desktop session.
session_startOpen the Windows Desktop stream, with optional stream_profile and resolution, FPS and bitrate overrides.
session_statusReport the state of the current session.
session_stopEnd the desktop session.
screen_captureCapture the current frame of the remote desktop.
provider_app_startLaunch an app registered in Apollo, used only when explicitly requested.

Frequently asked questions

It must already run Apollo or Sunshine with a Desktop application. The installer does not put anything on the Windows host.