remote-pc-mcp

remote-pc-mcp

通过可流式传输的 HTTP，将任何 PC 的能力——Shell、文件系统、后台进程、系统统计信息、屏幕截图、UI 控制和文件传输——开放给任何 MCP 客户端（Claude Desktop、Claude Code、Cursor、Cline、Continue、Windsurf、自定义 Agent，以及任何支持 Model Context Protocol 的客户端）。

将它部署到任何你想远程操控的机器上：家用服务器、桌面电脑、构建／CI 机器、媒体服务器、工作站或 Raspberry Pi。在另一台机器上，你选择的 AI Agent 可以在其上运行命令、管理文件、启动并监控后台任务、截屏以及操控桌面 UI。

传输方式采用 mcp SDK 的可流式传输 HTTP（stateless_http=True），因此服务器重启不会中断已连接的客户端。每个请求都是独立的——不会有过期的内存会话。

⚠️ shell_exec 会以启动服务器的用户身份在主机上运行任意命令。 Bearer 令牌的权限等同于 root。向外开放服务器前，请参阅安全性。

工具

工具	描述
shell_exec	运行任意 Shell 命令——返回 stdout、stderr 和退出代码
read_file	将文件读取为文本或 base64（用于二进制文件的回退方式）
write_file	将文本或二进制内容写入文件
list_directory	列出文件和目录，可选择递归列出
system_info	操作系统、CPU、RAM 和 GPU 统计信息（NVIDIA GPU 通过 nvidia-smi 获取；非 GPU 主机上没有此项）
start_process	在后台启动长时间运行的命令——返回 PID
get_process_output	通过 PID 轮询后台进程的 stdout／stderr，并在进程结束后返回其退出代码
kill_process	通过 PID 终止进程
download_file	直接将 URL 下载到此机器
take_screenshot	将整个桌面上的所有显示器截取为适合视觉模型查看的图像（屏幕坐标）
click	在屏幕截图中的 (x, y) 位置点击——左键／右键／中键，单击或多击
move_mouse	将光标移动到屏幕截图中的 (x, y) 位置，可选择使用动画效果
type_text	在当前聚焦的窗口中输入字符串
press_key	按下单个按键或快捷键组合（例如 enter、f11、ctrl+c、win+d）
scroll	向上或向下滚动鼠标滚轮，可选择指定位置

要求

• Python 3.10+
• Windows 10/11，或使用 systemd 的 Linux（用于自动启动）

安装

在你要控制的机器上：

git clone https://github.com/raghibrm/remote-pc-mcp
cd remote-pc-mcp
cp .env.example .env

在 .env 中设置一个强令牌：

REMOTE_PC_MCP_TOKEN=your-long-random-token-here

生成一个令牌：

# Windows
python -c "import secrets; print(secrets.token_hex(32))"

# Linux / macOS
openssl rand -hex 32

然后运行安装程序：

# Windows
install.bat

# Linux
chmod +x install.sh
./install.sh

就是这样——只需一条命令。安装程序会：

• 安装 Python 依赖项
• 注册服务器，使其在每次登录时以隐藏方式启动（Windows 上使用启动文件夹快捷方式，Linux 上使用 systemd 用户单元）
• 立即启动服务器
• 在崩溃时通过指数退避机制进行监控并重启（5→10→20→40→60 秒；运行满 5 分钟后重置）
• 重启后仍会自动运行——设置一次，永久运行

验证服务是否已启动

curl http://localhost:8765/health
# {"status":"ok","server":"remote-pc-mcp","version":"0.5.0"}

何时需要重新运行安装程序

install.bat / install.sh 支持幂等执行和自我修复。在以下情况发生后，可随时重新运行：

• 你将仓库移动到了其他文件夹
• 你将 Python 重新安装或升级到了其他路径
• 你重装了机器，并希望恢复自动启动

日常使用时无需操心这些。

重启后

自动启动会在你登录 Windows 时触发。重启后如果停留在锁屏界面，守护进程不会启动，直到有人登录。这是有意为之——启用 Windows 自动登录来实现完全无人值守的重启，会让任何能实际接触机器的人都能进入已登录的桌面，这对远程控制工具来说并非合适的取舍。

如果你需要在重启后恢复守护进程，但又无法走到 PC 前，可以通过 Remote Desktop 或 Tailscale SSH 远程登录。登录后，启动项快捷方式会触发，守护进程也会启动。

Linux 则不同：install.sh --linger 会运行 sudo loginctl enable-linger $USER，因此 systemd 用户单元无需任何人登录也能在重启后运行。systemd 用户服务不存在自动登录的安全问题，因为它们不会授予交互式桌面访问权限——只会让用户范围内的守护进程持续运行。

卸载

# Windows
install.bat --uninstall

# Linux
./install.sh --uninstall

移除自动启动项，并停止正在运行的服务端和监督进程。

前台运行（开发）

如需临时运行并显示控制台输出，且不启用自动启动：

python server.py

就是这样——无需特殊脚本。常规的受监督安装请使用 install.bat / install.sh。

或从 PyPI 安装

pip install remote-pc-mcp
remote-pc-mcp          # run the server in the foreground
remote-pc-mcp-daemon   # supervised: restarts the server on crash

使用 pip 安装会提供服务端和监督进程命令，但不会注册自动启动项。如需在登录时自动启动，请使用上文的克隆和安装脚本方式。.env、日志和 .state/ 位于 REMOTE_PC_MCP_HOME（默认值：工作目录）。

添加到 MCP 客户端

大多数 MCP 客户端使用相同的 JSON 架构；配置文件的位置各不相同。示例：

{
  "mcpServers": {
    "remote-pc": {
      "type": "http",
      "url": "http://YOUR_PC_IP_OR_HOSTNAME:8765/mcp",
      "headers": {
        "Authorization": "Bearer your-long-random-token-here"
      }
    }
  }
}

配置位置：

客户端	配置文件
Claude Code	项目根目录中的 .mcp.json（或用户级配置 ~/.claude.json）
Claude Desktop	claude_desktop_config.json（Settings → Developer → Edit Config）
Cursor	.cursor/mcp.json
Cline / Continue / Windsurf	每个客户端都有自己的 MCP 服务面板——将 JSON 粘贴到那里
自定义 Agent	Agent 读取 MCP 服务定义的位置

对于 Tailscale 用户，URL 中可以使用 MagicDNS 主机名：

"url": "http://your-pc.tail12345.ts.net:8765/mcp"

重启（或重新加载）客户端。工具会自动显示。"remote-pc" 键只是一个标签——可以按需命名。

安全

shell_exec 会以启动服务端的用户身份在主机上运行任意命令。这是有意为之——正是这一点让该服务端能够用于远程控制 PC。但这也意味着：

• Bearer 令牌的权限等同于 root。 生成一个 32 字节的十六进制令牌，仅将其存储在 .env 中（该文件已加入 git 忽略规则），并像密码一样妥善保管。
• 切勿在没有 TLS 和反向代理（nginx、Caddy、Cloudflare Tunnel）的情况下将服务端暴露到公共互联网。
• 使用 Tailscale（强烈建议）：绑定到你的 Tailscale IP（在 .env 中设置 REMOTE_PC_MCP_HOST=100.x.x.x），这样监听器只能由 tailnet 中的设备访问。
• 如果你信任 LAN 上的所有设备且令牌足够强，使用 REMOTE_PC_MCP_HOST=0.0.0.0 进行仅限 LAN 的部署是合理的。不要在不受信任的网络中这样做。

令牌使用 secrets.compare_digest（恒定时间）进行比较。所有错误消息都会经过净化处理，在返回给客户端之前移除绝对路径、主目录和令牌。

配置

除 REMOTE_PC_MCP_TOKEN 外，所有环境变量均为可选项。

变量	默认值	描述
REMOTE_PC_MCP_TOKEN	(必填)	客户端必须提供的 Bearer 令牌
REMOTE_PC_MCP_HOST	0.0.0.0	绑定地址。设置为 Tailscale IP 可限制可访问范围
REMOTE_PC_MCP_PORT	8765	监听端口
REMOTE_PC_MCP_ALLOWED_HOSTS	(空)	用逗号分隔的 DNS 重绑定防护允许列表。留空则禁用（默认设置——不适用于 tailnet 的威胁模型）
REMOTE_PC_MCP_MAX_SHELL_TIMEOUT	600（秒）	单次调用 shell_exec 的超时时间上限
REMOTE_PC_MCP_MAX_READ_BYTES	50 MB	read_file 的大小上限
REMOTE_PC_MCP_MAX_WRITE_BYTES	50 MB	write_file 的大小上限
REMOTE_PC_MCP_MAX_DOWNLOAD_BYTES	2 GB	download_file 的大小上限
REMOTE_PC_MCP_SCREEN_MAX_EDGE	1568（像素）	take_screenshot 图像的最长边。设为 0 可关闭限制
REMOTE_PC_MCP_SCREEN_MAX_PIXELS	1150000	take_screenshot 图像的总像素数。设为 0 可关闭限制

修改 .env 后，重启服务以使新值生效：

# Windows: easiest path is just re-run the installer (idempotent)
install.bat --uninstall && install.bat

# Linux
systemctl --user restart remote-pc-mcp

日志与故障排除

仓库根目录中有两个日志文件，都会自动轮转：

文件	内容	轮转
server.log	应用事件 + uvicorn 启动/访问日志	10 MB × 5
daemon.log	监督程序事件（崩溃、重启、退避）	2 MB × 3

服务没有响应？

# Is the listener up locally?
curl http://localhost:8765/health

# What's the supervisor seeing?
tail -f daemon.log

# Linux: full journal
journalctl --user -u remote-pc-mcp -f

# Windows: is the autostart registered?
explorer shell:startup    # look for remote-pc-mcp.lnk

重启服务后，MCP 客户端提示缺少工具？

可流式传输的 HTTP 传输机制旨在确保重启不会导致客户端失效，但客户端仍需发出请求才能发现服务已更新。首先，调用此服务中的任意工具（例如，让你的 Agent 运行 system_info）——客户端会重试连接。如果仍然失败，请在客户端中重新连接 MCP 服务（Claude Code：/mcp；Cursor：刷新 MCP 面板），或重启客户端。

进程卡住 / 端口已被占用？

# Windows
install.bat --uninstall && install.bat

# Linux
./install.sh --uninstall && ./install.sh

界面操作工具

take_screenshot、click、move_mouse、type_text、press_key 和 scroll 需要交互式桌面会话：

• Windows：用户必须已登录且屏幕已解锁。在 Session 0 下运行的服务无法访问桌面。通过“启动”文件夹安装即可满足这一条件——守护进程会在你的用户会话中运行。
• Linux：需要 X11 或 Wayland 会话。仅就截图而言，请安装 scrot、gnome-screenshot 或 ImageMagick 的 import——sudo apt install scrot 是最简单的选择。

屏幕坐标

视觉模型看到的是缩小到适合其图像限制的截图，因此它返回的坐标对应缩小后的图像。所以 take_screenshot 会缩小桌面图像，使最长边不超过 REMOTE_PC_MCP_SCREEN_MAX_EDGE 像素，且总像素数不超过 REMOTE_PC_MCP_SCREEN_MAX_PIXELS。默认值与 Claude API 的标准图像限制相符，因此客户端不会再次缩小图像。结果包含一张 JPEG 图像，以及一个 JSON 块，其中包含图像尺寸、缩放比例、桌面几何信息和主机上全分辨率 PNG 的路径。

click、move_mouse 和 scroll 接受该图像像素中的 (x, y) 坐标。服务会将每个坐标映射回真实桌面，包括位于主显示器左侧或上方、桌面坐标为负数的显示器。每次调用还会返回所使用的 desktop_x、desktop_y。坐标映射仅取决于桌面的当前尺寸，因此只要使用相同的图像尺寸，客户端无需先截图即可点击。将两个限制都设为 0，即可获取全分辨率图像，使每个桌面像素对应一个图像像素。坐标仍从图像左上角开始计算。

在 Windows 上，服务会以逐显示器 DPI 感知模式运行，因此无论显示器缩放比例如何，捕获画面和鼠标操作都使用各显示器上的物理像素。

开发

项目结构：

文件	用途
server.py	MCP 服务——工具、身份验证、传输
daemon.py	监控程序——启动服务，并在崩溃时通过退避机制重启
_logging.py	共享日志配置——为应用和 uvicorn 日志记录器使用同一个处理器
_screen.py	屏幕空间：截图的尺寸设置方式，以及像素如何映射到桌面
install.{bat,sh}	单一入口：默认执行安装，--uninstall 用于卸载

测试

tests/ 下有一套独立的测试套件，会在高位端口上启动自己的隔离服务，并使用临时令牌；它会测试每个工具，并验证服务在运行中重启后不会将客户端拒之门外。它不会影响正在运行的生产服务。

pip install -r requirements-dev.txt
python -m pytest tests/ -v

许可证

MIT