Moonlight Desktop MCP

Moonlight Desktop MCP

A local stdio MCP server for visual computer use on a paired Apollo or Sunshine Windows Desktop. MCP clients and coding agents can capture the remote screen, locate visible controls, and send mouse or keyboard input in that same coordinate space.

The server runs on the controlling macOS, Linux, or Windows machine and talks to the Windows host over Moonlight/GameStream. It is for visible tasks such as opening an application, changing a setting, or dismissing a dialog—not for a hidden Windows shell, registry, process access, or a Windows-side agent.

Choose your path

Most people need only the first two links. The commands in the development guide are deliberately not part of the normal installation path.

Discovery for clients and agents

• server.json provides the standard MCP server identity, repository, version, and canonical installation page for catalogs and clients. Because this project requires a controller-native build, the card points to the managed installer instead of advertising an npm package or a hosted remote endpoint.
• llms.txt is a compact, model-readable map of the canonical installation, use, tool, architecture, and safety documentation.
• AGENTS.md guides coding agents working in this repository; docs/AGENT-GUIDE.md guides agents operating the installed MCP. Codex users can also install the bundled moonlight-desktop-operator skill.

Install or update

Run one command on the computer that will run the MCP—your Mac, Linux, or Windows machine, not the Windows PC being controlled. Re-run the same command later to update a clean installation.

This project is not distributed as a ready-to-run npm or npx package. Use the platform installer below so the native Moonlight bridge and controller dependencies are built and checked together.

macOS and 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

The installer obtains controller-side build dependencies, creates or refreshes its own checkout, builds the native Moonlight bridge, and verifies readiness. It preserves pairing data outside that checkout. When the Codex CLI is already available, it adds the moonlight-desktop MCP entry if one does not exist. It does not install anything on the Windows host; that host must already run Apollo or Sunshine with a Desktop application. See Install and update for review, pinning, and other MCP clients.

Use the MCP

The normal computer-use loop is:

1. Pair once: host_status → pairing_begin → enter the returned PIN at the returned Apollo URL → pairing_status.
2. Optionally configure Wake-on-LAN with profile_wol_configure if the PC may be asleep or powered off.
3. Before each task, call desktop_channel_status, follow its nextAction, then call session_preflight and session_start when the transport is available and no launch preparation is in progress.
4. Capture the Desktop, use that current frame to establish whether the requested app or setup state is visibly available, locate a target, input in that frame's coordinate space, and capture again to verify the result.
5. Call session_stop when finished.

session_start always opens the Desktop. An application need not be registered in Apollo to be opened from the Desktop or Start menu. Use provider_app_start only when the user explicitly asks to launch an Apollo-registered provider app. The detailed setup, safety boundaries, and examples are in Use the MCP.

What it provides

The complete tool contract is in docs/TOOLS.md. The bundled agent guidance is in docs/AGENT-GUIDE.md.

Scope and safety

• One Desktop stream at a time. If another GameStream client owns the channel, the MCP reports it and does not take it over.
• Remote app availability, installer progress, account state, and license state are established only through the current rendered Desktop, never through a remote shell, registry, or process inspection.
• Pairing keys, frames, OCR cache, and Wake-on-LAN settings stay on the controlling machine.
• H.264 Desktop video defaults to 1920×1080/30fps at 20 Mbps. Pass stream_profile: "low_bandwidth" to session_start for 1280×720/30fps at 8 Mbps on a slow connection; width, height, FPS, and bitrate remain optional per-session overrides. Audio, clipboard, file transfer, HEVC/AV1, and session recovery are out of scope.
• Every meaningful action should be visually verified using a fresh capture.

For compatibility, troubleshooting, architecture, and security details, see docs/COMPATIBILITY.md, docs/TROUBLESHOOTING.md, docs/ARCHITECTURE.md, and docs/SECURITY.md.