claude-bridge

Ever wanted to tell Claude to do something on your PC while you're away? It's a really bad idea, but here's a way to do it anyway: setting up a custom MCP connector. It requires a fair number of moving parts, but it's doable.

Remote-controlled shell/GUI access to your own machine from Claude (or any MCP-speaking client), gated by phone approval and audit logging. Every action — reading a file, running a command, logging into an app — requires an explicit tap on your phone via ntfy. Root-level commands additionally require a TOTP code.

This is not a toy. It gives an AI agent the ability to run real commands as root on your machine, once you approve it. Read the Security model section before you deploy this anywhere.

Unofficial, community project. Not affiliated with or endorsed by Anthropic. "Claude" and "MCP" are used here only to describe compatibility.

Quickstart

git clone <this-repo-url> claude-bridge
cd claude-bridge
cp .env.example .env        # edit CLAUDE_BRIDGE_PUBLIC_URL once you have a hostname
./setup.sh                  # generates secrets, prints your OAuth password + TOTP QR
docker compose up -d        # brings up the OAuth/MCP server + bundled ntfy
sudo ./agent/install-agent.sh "$(pwd)/data"   # installs the native executor

That's the "brain" (containerized, no host access) and the "agent" (native, the only piece that actually touches your machine) both running. Now:

1. Put a reverse proxy or tunnel (Caddy, nginx, Cloudflare Tunnel, Tailscale Funnel, whatever you already use) in front of port 8000, and set CLAUDE_BRIDGE_PUBLIC_URL in .env to that public hostname before running setup.sh/docker compose up (it becomes the OAuth issuer and the JWT's aud/iss claims — it must match exactly what you expose).
2. If your phone needs to reach ntfy from outside your LAN, expose port 8091 too (same proxy/tunnel), and subscribe to the notify topic printed by setup.sh in the ntfy app.
3. In claude.ai: Settings → Connectors → Add custom connector, URL https://your-hostname/mcp, authorize with the password setup.sh printed.
4. Ask Claude to do something. Approve on your phone. Done.

Architecture

The core design decision: the container never touches your host. Everything that needs real host access runs natively, outside Docker, installed by a plain shell script you can read top to bottom.

┌─────────────────────────── "brain" (Docker) ───────────────────────────┐
│  server.py        OAuth 2.1 + PKCE, and the MCP endpoint (merged into  │
│                    one ASGI app -- no separate reverse proxy needed)   │
│  agent_server.py   Unix-socket listener: submit/status/list/cancel/    │
│                    confirm_totp                                       │
│  control_listener  subscribes to ntfy, processes Approve/Deny          │
│  status_server.py  read-only dashboard + JSON API                      │
└──────────────────────────────┬──────────────────────────────────────────┘
                                │  shared bind-mounted ./data volume
                                │  (queue.db, agent.sock, secrets)
┌───────────────────────────────┴──────────────────────────────────────────┐
│  "agent" (native, installed by agent/install-agent.sh)                   │
│  executor.py       polls the SAME queue.db, actually runs approved       │
│                    requests as a dedicated system user, with a           │
│                    narrowly-scoped sudo rule for the exec_sudo tier      │
└────────────────────────────────────────────────────────────────────────┘

A request's life cycle: MCP tool call → written to the shared queue → ntfy push notification → you tap Approve → control_listener records the decision → (exec_sudo: you also submit a TOTP code) → the native executor.py picks it up and actually runs it → result written back to the queue → Claude reads it via check_status.

Every request carries a content_hash (sha256 of action+detail+path+window_name+id) that approval/TOTP steps must match exactly, so an approval for one request can never be replayed against a different one.

Action tiers

run_command(action, summary, detail, path, window_name, timeout_seconds):

action	uses	notes
read	path	reads a file directly, no shell, capped at 300KB
write	path + detail (new content)	approval notification shows a unified diff
exec	detail (shell command)	runs as the agent user; set CLAUDE_BRIDGE_DISPLAY to let it launch GUI apps (see below); default timeout 60s
exec_sudo	detail (shell command)	runs as root via a denylist-backed sudo wrapper; default timeout 120s; requires a TOTP code after phone approval
gui_type	detail (text to type) + window_name (required)	types into a specific already-open window via xdotool; refuses if no window matches; the typed text is never logged or shown in the notification -- only its length and target window

TTLs before auto-expiry: read/write 600s, exec/exec_sudo 300s, gui_type 180s. timeout_seconds overrides the exec/exec_sudo default (max 1800s).

MCP tools

• run_command(...) — submit a request, returns {id, status: "pending", expires_at}
• check_status(request_id) — poll one request
• list_pending() — everything still pending or awaiting_totp
• cancel_request(request_id) — withdraw your own not-yet-executed request
• confirm_totp(request_id, code) — submit the TOTP code for an exec_sudo request stuck at awaiting_totp, entirely from chat. This is what makes the whole thing phone-only capable — no terminal needed for the sudo tier.

GUI apps (optional)

To let exec/gui_type interact with a real desktop session:

1. On the desktop, grant the agent user X11 access (re-run this every login, e.g. via your desktop environment's autostart):

   xhost +SI:localuser:claude-bridge-agent
   

2. Uncomment CLAUDE_BRIDGE_DISPLAY=:0 in /etc/systemd/system/claude-bridge-agent.service and systemctl daemon-reload && systemctl restart claude-bridge-agent.

Understand what this means: the agent user can now draw on and interact with whatever's on that real, logged-in desktop. This is a deliberate capability, not a default — don't enable it unless you actually want it.

Security model

• Nothing executes without a phone tap. No exceptions, no bypass flags.
• exec_sudo additionally requires a TOTP code after the phone approval — two independent factors. The TOTP secret lives only in data/totp_secret.json.
• Approval/cancel/TOTP steps are bound to content_hash, preventing cross-request replay (cancel_request is the one exception, by design — it can only move a request further from execution, never closer).
• sudo_runner.py is the entire sudo attack surface for the agent user — root-owned so the agent can execute it (via the scoped NOPASSWD sudoers rule install-agent.sh installs) but never modify it. It has a denylist regex for catastrophic patterns (rm -rf /, raw-device dd/mkfs, fork bombs) as a last-resort backstop — the real boundary is the approval pipeline upstream of it.
• The brain container has zero host access. No privileged mode, no host PID namespace, no docker socket mount. If it's fully compromised, the blast radius is "attacker controls your OAuth server and can submit fake requests to the same approval queue" — which still requires your phone tap (and TOTP, for root) to do anything.
• Cross-UID data sharing: the brain container and the native agent are different UIDs sharing one bind-mounted directory. install-agent.sh and the app code both default to permissive (777/666) permissions on that directory as the pragmatic default for a single-host setup. If you want tighter isolation, put both under a shared group instead and adjust accordingly.
• GUI access is opt-in and explicit (see above) — a compromised or buggy agent process with CLAUDE_BRIDGE_DISPLAY set could interact with whatever's on the real desktop session.

Configuration reference

All via .env (read by docker compose) or docker-compose.yml's environment: block:

variable	default	what
CLAUDE_BRIDGE_PUBLIC_URL	http://localhost:8000	your externally-reachable hostname, no path suffix — becomes the OAuth issuer/audience
CLAUDE_BRIDGE_PORT	8000	host port for the MCP/OAuth endpoint
CLAUDE_BRIDGE_STATUS_PORT	8092	host port for the status dashboard

Native agent (agent/install-agent.sh writes these into the systemd unit):

variable	what
CLAUDE_BRIDGE_DB_PATH, CLAUDE_BRIDGE_AUDIT_LOG, CLAUDE_BRIDGE_HEARTBEAT_PATH, CLAUDE_BRIDGE_SOCK_PATH	paths into the shared ./data directory
CLAUDE_BRIDGE_SUDO_RUNNER, CLAUDE_BRIDGE_AGENT_PYTHON	how the exec_sudo tier invokes sudo_runner.py
CLAUDE_BRIDGE_DISPLAY	optional, e.g. :0 — enables GUI apps (see above)

Troubleshooting

• sqlite3.OperationalError: attempt to write a readonly database — the queue.db was created by one side (container or native agent) with permissions the other side's UID can't write to. bridge_queue.py chmods it to 666 on every init_db() call, but if you're still hitting this, check ls -la ./data.
• PermissionError reaching the data directory from the native agent — the shared data directory needs to be traversable by the agent user through every parent directory, not just have open permissions itself. Putting your checkout inside a locked-down home directory (some distros ship ~ as drwx--x---) will break this even if ./data itself is wide open. Either put the project somewhere globally traversable (e.g. /opt/claude-bridge), or add the agent user to a group with access to your home directory.
• ntfy: "auth is unconfigured for this server" — NTFY_AUTH_FILE must be set for ntfy user add to work at all; docker-compose.yml already sets this, but if you changed it, check that first.
• SELinux (Fedora/RHEL/etc): containers failing to write to bind mounts — the compose file already appends :z to the volume mounts. If you added new mounts, do the same, or you'll see avc: denied entries in journalctl / ausearch -m avc.
• Fresh chat claims a tool (usually confirm_totp) doesn't exist — claude.ai caches the tool list per connector session, not per conversation. Fully disconnect/reconnect the connector in Settings → Connectors rather than just starting a new chat.

License

MIT — see LICENSE.