Moonlight Desktop MCP

Moonlight Desktop MCP

一个本地 stdio MCP 服务，用于在已配对的 Apollo 或 Sunshine Windows 桌面上进行可视化操作。MCP 客户端和编码 Agent 可以捕获远程屏幕、定位可见控件，并在相同的坐标空间中发送鼠标或键盘输入。

服务运行在负责控制的 macOS、Linux 或 Windows 机器上，并通过 Moonlight/GameStream 与 Windows 主机通信。它适用于打开应用、更改设置或关闭对话框等可见任务，不用于访问隐藏的 Windows Shell、注册表、进程，也不用于 Windows 端的 Agent。

选择适合你的路径

你的目标	从这里开始
安装、更新并运行 MCP	安装和更新
配对 PC 并使用可视化工具	使用 MCP
自行克隆、修改、测试或构建源代码	从源代码开发
向 Agent 提供简明的操作规范	Agent 操作指南

大多数人只需查看前两个链接。开发指南中的命令有意不纳入常规安装流程。

面向客户端和 Agent 的发现信息

• server.json 为目录和客户端提供标准 MCP 服务标识、仓库、版本和规范安装页面。由于此项目需要使用控制器原生构建版本，因此该条目指向托管安装程序，而不是宣传 npm 包或托管的远程端点。
• llms.txt 是一份精简、便于模型读取的指南，列出了规范的安装、使用、工具、架构和安全文档。
• AGENTS.md 为在此仓库中工作的编码 Agent 提供指南；docs/AGENT-GUIDE.md 为操作已安装 MCP 的 Agent 提供指南。Codex 用户还可以安装随附的 moonlight-desktop-operator 技能。

安装或更新

在将运行 MCP 的电脑上执行一条命令——也就是你的 Mac、Linux 或 Windows 机器，而不是被控制的 Windows PC。之后可再次运行同一条命令，以更新干净的安装。

此项目不以可直接运行的 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 主机上安装任何内容；该主机必须已运行带有 Desktop 应用程序的 Apollo 或 Sunshine。有关审核、固定版本及其他 MCP 客户端的信息，请参阅安装和更新。

使用 MCP

常规的电脑操作循环如下：

1. 配对一次：host_status → pairing_begin → 在返回的 Apollo URL 中输入返回的 PIN → pairing_status。
2. 如果 PC 可能处于睡眠或关机状态，可选择使用 profile_wol_configure 配置 Wake-on-LAN。
3. 每项任务开始前，调用 desktop_channel_status 并按照其 nextAction 操作；当传输可用且没有正在进行的启动准备时，再调用 session_preflight 和 session_start。
4. 捕获桌面画面，根据当前帧确认所请求的应用或设置状态是否清晰可见，定位目标，在该帧的坐标空间中输入，然后再次捕获画面以验证结果。
5. 完成后调用 session_stop。

session_start 始终会打开桌面。无需在 Apollo 中注册应用，也可从桌面或“开始”菜单打开应用。仅当用户明确要求启动已在 Apollo 中注册的提供方应用时，才使用 provider_app_start。详细的设置说明、安全边界和示例见 使用 MCP。

提供的功能

需求	MCP 工具
配对、检查和唤醒主机	host_status、配对工具、profile_status、profile_wol_configure、host_wake
检查、启动和停止桌面	session_preflight、session_start、session_status、session_stop
查看远程屏幕	screen_capture、OCR、文本/模板查找、裁剪、差异比较和等待
交互并确认	鼠标、拖动、滚动、文本、命名按键/热键工具和视觉等待

完整的工具契约见 docs/TOOLS.md。随附的 Agent 指南见 docs/AGENT-GUIDE.md。

范围与安全

• 一次只能有一个桌面流。如果另一个 GameStream 客户端占用了通道，MCP 会报告这一情况，不会接管通道。
• 远程应用的可用性、安装程序进度、账户状态和许可证状态，仅通过当前渲染的桌面确认，绝不通过远程 Shell、注册表或进程检查确认。
• 配对密钥、帧、OCR 缓存和 Wake-on-LAN 设置均保留在控制端计算机上。
• H.264 桌面视频默认设置为 1920×1080/30fps、20 Mbps。慢速连接时，将 stream_profile: "low_bandwidth" 传递给 session_start，即可使用 1280×720/30fps、8 Mbps；宽度、高度、FPS 和比特率仍可按会话进行可选覆盖。音频、剪贴板、文件传输、HEVC/AV1 和会话恢复均不在支持范围内。
• 每项有实际意义的操作都应通过新捕获的画面进行视觉验证。

有关兼容性、故障排除、架构和安全的详情，请参阅 docs/COMPATIBILITY.md、 docs/TROUBLESHOOTING.md、 docs/ARCHITECTURE.md 和 docs/SECURITY.md。