AI导哈

远程Mac控制服务

一个通过MCP协议提供AI服务远程控制Mac的服务器，支持执行shell命令、读写文件、运行AppleScript，并通过OAuth 2.0 + PKCE确保安全。

  • by Hexpy-Games
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 Hexpy-Games/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 <your-token>
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上的四个工具：

工具 它做什么
shell_exec 运行任何zsh命令
osascript 运行AppleScript（UI自动化、应用程序控制）
file_read 读取文件或列出目录
file_write 写入文件（根据需要创建目录）

尝试的示例提示：

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

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

配置

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

变量 默认值 描述
PORT 3232 MCP服务器监听的端口
BASE_URI http://localhost:3232 此服务器的公共URL必须与您的隧道URL匹配
NODE_ENV development 设置为 production 部署时
BLOCKED_COMMANDS （空） 要阻止的逗号分隔的子字符串 shell_exec
REDIS_URL （未设置） Redis连接URL——生产中需要
REDIS_TLS 0 设置为 1 为Redis连接启用TLS

瑞迪斯

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.

可用工具

工具 说明
shell_exec 执行a zsh Mac上的命令。异步运行；支持并发命令。返回stdout、stderr和退出代码。
osascript 执行AppleScript。脚本被写入私有临时目录以防止TOCTU竞争。用于UI自动化和应用程序控制。
file_read 读取文件内容或列出目录。用途 fs.promises 直接——没有贝壳产卵。
file_write 将内容写入文件。如果需要，创建中间目录。

安全说明

  • 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/<filename>

通过管理 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
  3. 跑 npm run lint 和 npm run typecheck --两者都必须通过
  4. 打开一个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或任何其他人工智能服务提供商，也不由其认可或赞助。

相关 MCP