remote-control-mcp

An MCP server that gives AI services (Claude, Cursor, etc.) remote control of your Mac — execute shell commands, read/write files, and run AppleScript — secured with OAuth 2.0 + PKCE.

Demo

Claude searches for a tteok shop on Naver Maps, gets driving directions, takes a screenshot, and emails the result. All done in the Claude app on iOS.

What it does

• Exposes your Mac as an MCP server reachable over the internet through a secure tunnel

• Runs shell commands (zsh) asynchronously and returns stdout, stderr, and exit code

• Reads and writes files and directories using fs.promises — no shell injection surface

• Executes AppleScript for UI automation and app control

• Protects every tool call with OAuth 2.0 + PKCE; token rotation revokes old tokens immediately

• Optional file server (port 3835) to share files from ~/Public/mcp-files/ via browser or any HTTP client

⚠️ Security Warning

This server provides remote shell execution on your Mac.

• OAuth 2.0 + PKCE protects the MCP endpoint — valid tokens are required for all tool calls

• PIN-gated authorization — connecting a new client requires a one-time PIN generated by rcmcp auth on your local machine. The PIN is never written to disk and is only accessible via localhost. Anyone who reaches /authorize without the PIN cannot obtain a token.

• The network layer is your second line of defense — always expose the server through an authenticated tunnel. Never bind directly to a public IP.

This server is designed for personal, single-user use behind a private tunnel. Do not expose it to untrusted networks.

Requirements

• macOS (Linux support planned; AppleScript tools are macOS-only)

• Node.js >=20.16.0 or >=22.3.0

• A tunnel to expose the server — Cloudflare Tunnel, ngrok, or Tailscale (see below)

• Redis (required in production for token persistence; in-memory fallback used without it)

Quick Start

Automated (recommended)

setup.sh handles everything interactively — dependencies, .env, build, tunnel, LaunchAgent, and CLI:

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

Manual

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

Then set up a tunnel (see below) and add the server URL to your AI client.

Tunnel Options

Never bind the server directly to a public IP. Use one of the following:

setup.sh (Cloudflare Tunnel and ngrok). Tailscale and direct IP require manual setup.

Option 1: Cloudflare Tunnel (recommended — free, stable URL)

setup.sh handles installation, authentication, DNS routing, and LaunchAgent registration automatically.

To set up manually:

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

One-shot (URL changes each run, useful for testing):

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

Option 2: ngrok (quick setup, generous free tier)

setup.sh handles installation, authtoken, and LaunchAgent registration automatically.

To set up manually:

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

The ngrok free tier assigns a random URL on each restart — update BASE_URI in .env after each restart, then run rcmcp restart server. Paid plans support a fixed static domain.

Option 3: Tailscale Funnel (manual setup only)

Tailscale is not yet supported by setup.sh. Set up manually:

brew install tailscale
tailscale up
tailscale funnel 3232
# Copy the https://...ts.net URL shown and set it as BASE_URI in .env

Tailscale Funnel gives you a stable *.ts.net HTTPS URL with no account beyond a free Tailscale plan.

Option 4: Direct IP (advanced, manual only)

Only use this if you understand the risks and have proper TLS termination in place:

1. Forward port 3232 on your router to your Mac

2. Set BASE_URI to your domain or public IP in .env

3. Terminate TLS at a reverse proxy — plain HTTP exposes OAuth tokens in transit

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

Connect to Claude

After the server is running and a tunnel is up:

1. Add the MCP server in Claude

In Claude.ai (desktop or web): go to Settings → Integrations → Add Integration and paste your server URL:

https://your-tunnel-url/mcp

Claude will immediately start an OAuth authorization flow.

2. Authorization

A browser window will open asking you to approve the connection. This is where you enter the Server PIN.

Get your PIN:

rcmcp auth

This generates a fresh one-time PIN, copies it to your clipboard, and waits for you to complete the authorization:

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

    9aRs-VhzM   (copied to clipboard)

  → Enter this PIN on the /authorize approval page.

  ⠙  Waiting for authorization...

Paste the PIN into the browser form and click Approve. The terminal will confirm automatically:

  ✓ Authorization complete

3. Start using remote tools

Once authorized, Claude has access to four tools on your Mac:

Example prompts to try:

• "Take a screenshot and describe what's on my screen"

• "What files are in my Downloads folder?"

• "Search for coffee shops near me on Maps and send me the directions"

Other clients: Any MCP-compatible client (Cursor, Windsurf, etc.) can connect using the same server URL. The OAuth flow is standard.

Configuration

Copy .env.example to .env and edit as needed.

Redis

Redis is required in production for token persistence and expiry. Without it, tokens are stored in memory and lost on restart.

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

# Homebrew
brew install redis && brew services start redis

Set REDIS_URL=redis://localhost:6379 in .env.

Available Tools

Security notes

• BLOCKED_COMMANDS is a last-resort safeguard, not a security boundary. Security is enforced at the OAuth + tunnel layer.

• Refresh token rotation revokes the previous token immediately.

• A default blocklist prevents the most catastrophic commands (rm -rf /, fork bombs, direct disk writes, etc.).

rcmcp CLI

setup.sh installs rcmcp, a management CLI for day-to-day operations:

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

Targets can be abbreviated: srv, tun, fs.

File Server (optional)

setup.sh can install an optional lightweight file server (port 3835) that serves files from ~/Public/mcp-files/ over HTTP. Useful for sharing or viewing Mac files from any browser, HTTP client, or AI service.

GET https://your-tunnel-url/files/<filename>

Managed via rcmcp start fileserver / rcmcp stop fileserver.

Development

# Run with live reload
npm run dev

# Type-check without emitting
npm run typecheck

# Lint
npm run lint

# Build
npm run build

Contributing

Reporting issues

• Bug: Open an issue with the prefix [bug]. Include OS version, Node version, reproduction steps, and expected vs. actual behavior.

• Feature request: Open an issue with the prefix [feat]. Describe the use case, not just the solution.

Submitting a PR

1. Fork the repo and create a branch from main

2. Follow branch naming conventions:

   • feat/ — new feature

   • fix/ — bug fix

   • docs/ — documentation only

   • chore/ — tooling, deps, CI

3. Run npm run lint and npm run typecheck — both must pass

4. Open a PR against main with a clear description of what and why

Commit style

Use Conventional Commits:

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

What gets accepted

• Security improvements

• New MCP tools that fit the "remote Mac control" scope

• Additional tunnel provider support

• Bug fixes

What gets rejected

• Changes that remove the OAuth requirement

• Features that broaden scope to multi-user or server-side use cases

License

MIT — Copyright (c) 2026 Hexpy Games & remote-control-mcp contributors

See LICENSE for the full text.

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Anthropic, Claude.ai, or any other AI service provider.