Remote Control MCP

遥控mcp

一个MCP服务器，它为AI服务（Claude、Cursor等）提供对Mac的远程控制——执行shell命令、读/写文件和运行AppleScript——由OAuth 2.0+PKCE保护。

演示

克劳德在Naver Maps上搜索tteok商店，获取行车路线，截图，并将结果通过电子邮件发送。所有这些都是在iOS上的Claude应用程序中完成的。

______________________________________________________________________

它做什么

• 将您的Mac暴露为可通过安全隧道通过互联网访问的MCP服务器
• 运行shell命令(zsh)异步返回stdout、stderr和退出代码
• 使用以下命令读取和写入文件和目录 fs.promises --无壳体注射表面
• 执行AppleScript以实现UI自动化和应用程序控制
• 使用OAuth 2.0+PKCE保护每个工具调用；令牌轮换会立即撤销旧令牌
• 用于共享文件的可选文件服务器（端口3835） ~/Public/mcp-files/ 通过浏览器或任何HTTP客户端

______________________________________________________________________

⚠️ 安全警告

此服务器提供 远程shell执行 在你的Mac上。

• OAuth 2.0+PKCE 保护MCP端点——所有工具调用都需要有效的令牌
• PIN门控授权 --连接新客户端需要由生成的一次性PIN rcmcp auth 在您的本地机器上。PIN永远不会写入磁盘，只能通过localhost访问。任何到达 /authorize 没有PIN就无法获得令牌。
• 网络层是你的第二道防线 --在暴露服务器之前，始终终止TLS。纯HTTP在传输过程中公开OAuth令牌，无论您使用的是域名还是原始IP。

此服务器专为私人隧道后的个人单用户使用而设计。不要将其暴露在不受信任的网络中。

______________________________________________________________________

需求

• macOS （计划支持Linux；AppleScript工具仅适用于macOS）
• Node.js >=20.16.0 或 >=22.3.0
• 暴露服务器的隧道——Cloudflare隧道、ngrok或Tailscale（见下文）
• 瑞迪斯 （生产中需要令牌持久性；在没有令牌持久性的情况下使用内存回退）

______________________________________________________________________

快速开始

自动（推荐）

setup.sh 以交互方式处理一切——依赖关系， .env、构建、隧道、LaunchAgent和CLI：

git clone https://github.com/hexpy-games/remote-control-mcp
cd remote-control-mcp
./setup.sh

手册

git clone https://github.com/hexpy-games/remote-control-mcp
cd remote-control-mcp
npm install
cp .env.example .env
# Edit .env — set BASE_URI to your tunnel URL
npm run build
npm start

然后设置一个隧道（见下文），并将服务器URL添加到您的AI客户端。

______________________________________________________________________

隧道选项（用于手动设置）

永远不要通过纯HTTP公开服务器。始终通过隧道或反向代理终止TLS：

setup.sh 自动化选项1和2 （Cloudflare隧道和ngrok）。

选项1:Cloudflare隧道（推荐-免费、稳定的URL）

brew install cloudflared

# Permanent subdomain (requires free Cloudflare account)
cloudflared tunnel login
cloudflared tunnel create remote-control-mcp
cloudflared tunnel route dns remote-control-mcp your-subdomain.yourdomain.com
# Set BASE_URI=https://your-subdomain.yourdomain.com in .env
cloudflared tunnel run remote-control-mcp

一次尝试（每次运行URL都会更改，这对测试很有用）：

cloudflared tunnel --url http://localhost:3232

选项2:ngrok（快速设置，慷慨的免费等级）

brew install ngrok
ngrok config add-authtoken 
ngrok http 3232
# Copy the https URL and set it as BASE_URI in .env

ngrok免费层在每次重启时分配一个随机URL--update BASE_URI 在 .env 每次重新启动后，然后运行 rcmcp restart server.付费计划支持固定的静态域。

选项3：自托管（高级）

仅当您有适当的TLS终止时才使用此选项：

1. 将路由器上的3232端口转发到Mac
2. 集 BASE_URI 到您的域名或公共IP .env
3. 在反向代理端终止TLS——纯HTTP在传输过程中暴露OAuth令牌

# Example: Caddy as a TLS-terminating reverse proxy
brew install caddy
# Caddyfile:
# your-domain.com {
#   reverse_proxy localhost:3232
# }
caddy run

______________________________________________________________________

联系克劳德

服务器运行并打开隧道后：

1.在Claude中添加MCP服务器

在 Claude.ai （桌面或网络）：转到 设置→ 集成→ 添加集成 并粘贴您的服务器URL：

https://your-tunnel-url/mcp

Claude将立即启动OAuth授权流。

2.授权

浏览器窗口将打开，要求您批准连接。这是你进入的地方 服务器PIN.

获取您的PIN码：

rcmcp auth

这将生成一个新的一次性PIN，将其复制到剪贴板，并等待您完成授权：

  Authorization PIN
  ────────────────────────────────────────

    9aRs-VhzM   (copied to clipboard)

  → Enter this PIN on the /authorize approval page.

  ⠙  Waiting for authorization...

将PIN粘贴到浏览器表单中，然后单击 批准终端将自动确认：

  ✓ Authorization complete

3.开始使用远程工具

一旦获得授权，Claude就可以访问Mac上的四个工具：

尝试的示例提示：

• *“截图并描述我屏幕上的内容”*
• *“我的下载文件夹中有哪些文件？”*
• *“在地图上搜索我附近的咖啡店，并给我发路线”*

其他客户： 任何兼容MCP的客户端（Cursor、Windsurf等）都可以使用相同的服务器URL进行连接。OAuth流程是标准的。

______________________________________________________________________

配置

复制 .env.example 到 .env 并根据需要进行编辑。

瑞迪斯

Redis是 生产中所需 用于令牌持久性和到期。没有它，令牌将存储在内存中，并在重新启动时丢失。

# Docker
docker run -d -p 6379:6379 redis:7-alpine

# Homebrew
brew install redis && brew services start redis

集 REDIS_URL=redis://localhost:6379 在 .env.

______________________________________________________________________

可用工具

安全说明

• BLOCKED_COMMANDS 是最后的保障措施， 不 安全边界。安全性是在OAuth+隧道层实施的。
• 刷新令牌轮换会立即撤销上一个令牌。
• 默认块列表可防止最灾难性的命令(rm -rf /、分叉炸弹、直接磁盘写入等）。

______________________________________________________________________

rcmcp命令行界面

setup.sh 安装 rcmcp，用于日常操作的管理CLI：

rcmcp status                    # server + tunnel + file server status and endpoint URL
rcmcp start [server|tunnel|fileserver|all]
rcmcp stop  [server|tunnel|fileserver|all]
rcmcp restart [server|tunnel|fileserver|all]
rcmcp logs [server|tunnel|fileserver|all] [-f]
rcmcp url                       # print current MCP endpoint URL
rcmcp update                    # git pull → rebuild → restart server
rcmcp uninstall                 # remove LaunchAgents, binary, and PATH entry

目标可以缩写为： srv, tun, fs.

______________________________________________________________________

文件服务器（可选）

setup.sh 可以安装一个可选的轻量级文件服务器（端口3835），用于从以下位置提供文件 ~/Public/mcp-files/ 通过HTTP。可用于从任何浏览器、HTTP客户端或AI服务共享或查看Mac文件。

GET https://your-tunnel-url/files/

通过管理 rcmcp start fileserver / rcmcp stop fileserver.

______________________________________________________________________

发展

# Run with live reload
npm run dev

# Type-check without emitting
npm run typecheck

# Lint
npm run lint

# Build
npm run build

______________________________________________________________________

贡献

报告问题

• 程序错误：打开前缀问题 [bug]包括操作系统版本、节点版本、复制步骤以及预期与实际行为。
• 功能请求：打开前缀问题 [feat]描述用例，而不仅仅是解决方案。

提交PR

1. 分叉repo并创建一个分支 main
2. 遵循分支命名约定：

- feat/ --新功能 - fix/ --bug修复 - docs/ --仅文档 - chore/ — 工具， deps， CI

1. 跑 npm run lint 和 npm run typecheck --两者都必须通过
2. 打开一个PR main 清楚地描述了什么以及为什么

提交风格

使用 常规提交:

feat: add Tailscale tunnel option
fix: prevent shell_exec hanging on commands with no output
docs: clarify Redis requirement in README
chore: upgrade MCP SDK to 1.25

什么被接受

• 安全改进
• 适合“远程Mac控制”范围的新MCP工具
• 额外的隧道提供商支持
• 错误修复

什么会被拒绝

• 删除OAuth要求的更改
• 将范围扩展到多用户或服务器端用例的功能

______________________________________________________________________

许可证

麻省理工学院--版权所有（c）2026 Hexpy Games&遥控mcp贡献者

看 许可证 全文。

______________________________________________________________________

免责声明

本项目不隶属于Anthropic、Claude.ai或任何其他人工智能服务提供商，也不由其认可或赞助。