claude-mac-bridge

MCP server that lets an AI agent delegate tasks to Claude Code on a remote Mac via SSH over Tailscale. Persistent sessions, 200k context, full Mac filesystem access.

Agent (server) → ask_claude tool → SSH → claude -p (Mac) → JSON response + session_id

Why

Your agent runs on a Linux server. Claude Code runs on a Mac with Homebrew, Docker, Xcode, and 200k context. Sometimes you need both.

This bridge:

• Gives your agent Mac access: file system, tools, local services

• Persists sessions: pass session_id back to continue conversations across hours

• Zero config on the Mac: Claude Code runs headless via -p, no GUI needed

• Full audit trail: every delegation logged to bridge.log with cost + duration

Related MCP server: mcp-home-server

Quick Start

# 1. Install
pip install mcp

# 2. Set up SSH key
ssh-keygen -t ed25519 -f ~/.ssh/mac_bridge
ssh-copy-id -i ~/.ssh/mac_bridge.pub user@<mac-tailscale-ip>

# 3. Set env vars
export CLAUDE_BRIDGE_SSH_HOST="user@100.x.x.x"
export CLAUDE_BRIDGE_CLAUDE_BIN="/opt/homebrew/bin/claude"

# 4. Run the server
python3 server.py

# 5. Wire into your MCP config (see Setup below)

Requirements

• Claude Code on the Mac (npm install -g @anthropic-ai/claude-code or Homebrew)

• GNU timeout for remote process cleanup, install via brew install coreutils on macOS (provides gtimeout). Falls back gracefully if unavailable, but remote Claude processes may outlive timed-out SSH connections without it.

• Tailscale on both machines

• Passwordless SSH (key-based auth) from server → Mac

• Python 3.10+ on the server

• mcp package (pip install mcp)

Setup

1. SSH key auth

# On server: generate a dedicated key
ssh-keygen -t ed25519 -f ~/.ssh/mac_bridge

# Copy to Mac
ssh-copy-id -i ~/.ssh/mac_bridge.pub user@<mac-tailscale-ip>

# Verify
ssh -i ~/.ssh/mac_bridge user@<mac-tailscale-ip> "echo ok"

2. Configure

3. Wire into MCP config

mcp_servers:
  claude_bridge:
    command: "python3"
    args: ["/path/to/server.py"]
    env:
      CLAUDE_BRIDGE_SSH_HOST: "user@100.x.x.x"
      CLAUDE_BRIDGE_CLAUDE_BIN: "/opt/homebrew/bin/claude"
    timeout: 620  # must exceed CLAUDE_BRIDGE_TIMEOUT

API

ask_claude(task, context?, resume_session_id?)

Returns: Claude's response with session_id, cost, and duration appended.

# Basic
result = ask_claude(task="Write a Python script that reads a CSV and...")

# With context
result = ask_claude(
    task="Find the bug",
    context="def foo(): ...\nError: TypeError..."
)

# Persistent session
r1 = ask_claude(task="Review this PR")
r2 = ask_claude(
    task="Fix the first issue you found",
    resume_session_id="<session_id from r1>"
)

Session Chaining

Every response includes a session_id. Pass it back as resume_session_id to continue the same conversation, Claude remembers all prior context, files read, and decisions made.

Rule: always chain session_ids for related tasks. Without resume_session_id, each call is a cold start.

r1 = ask_claude(task="Build the auth module")
# r1 contains: session_id = "abc123"

r2 = ask_claude(task="Add rate limiting to the auth module", resume_session_id="abc123")
r3 = ask_claude(task="Write tests for all of it", resume_session_id="abc123")

Long Tasks: tmux Blocking Loop

The MCP tool has a hard wall-clock timeout (default 600s). For tasks that may run longer, project scaffolding, npm installs, multi-file builds, use this tmux pattern instead. It blocks until Claude finishes, auto-handles confirmation prompts, and returns the full result + session_id.

#!/usr/bin/env bash
MAC="user@<mac-tailscale-ip>"
TMUX="/opt/homebrew/bin/tmux"
CLAUDE="/opt/homebrew/bin/claude"
SESSION="agent-work"
MAX_WAIT=3600   # 60 min ceiling
POLL=45

# 1. write task to file (avoids SSH quoting hell)
scp /tmp/task.md "$MAC:~/task.md"

# 2. start fresh tmux session
ssh "$MAC" "$TMUX kill-session -t $SESSION 2>/dev/null; \
  $TMUX new-session -d -s $SESSION -x 220 -y 50"

# 3. launch claude
ssh "$MAC" "$TMUX send-keys -t $SESSION \
  '$CLAUDE -p "Read ~/task.md and execute every step." \
  --output-format json --dangerously-skip-permissions 2>&1 | tee ~/task_output.json' Enter"

# 4. blocking poll -- auto-answer confirmations, exit on shell prompt
elapsed=0
while [ $elapsed -lt $MAX_WAIT ]; do
  sleep $POLL
  elapsed=$((elapsed + POLL))
  pane=$(ssh "$MAC" "$TMUX capture-pane -t $SESSION -p 2>/dev/null | tail -10")

  # auto-approve confirmation prompts
  if echo "$pane" | grep -qiE 'do you want|allow|yes.*no|\[y/n\]|approve|1\).*2\)'; then
    ssh "$MAC" "$TMUX send-keys -t $SESSION '2' Enter"
    sleep 3; continue
  fi

  # shell prompt = claude exited
  echo "$pane" | grep -qE '^\s*(%|\$|>)\s*$' && break
done

# 5. grab result + session_id
result=$(ssh "$MAC" "cat ~/task_output.json 2>/dev/null")
session_id=$(echo "$result" | python3 -c \
  "import json,sys; print(json.load(sys.stdin).get('session_id',''))" 2>/dev/null)

# 6. cleanup
ssh "$MAC" "$TMUX kill-session -t $SESSION 2>/dev/null; rm -f ~/task.md ~/task_output.json"
echo "done in ${elapsed}s | session_id: $session_id"

When to use tmux vs MCP tool:

If unsure → tmux. A 30s task in tmux costs nothing extra. A 12-min task in the MCP tool gets killed at 10 min.

Monitoring

python3 monitor.py                    # live feed (tails bridge.log)
python3 monitor.py /path/to/bridge.log

Color-coded live TUI showing start/done/error/timeout events with task previews, response length, cost, and duration.

Troubleshooting

Security

• bridge.log contains full task/response history, it is gitignored, keep it local

• Never commit .env or SSH private keys

• --dangerously-skip-permissions is passed to Claude so it can use tools without interactive prompts, only use this on a trusted Mac you control

• The SSH command runs as-is on your Mac, do not expose this bridge to untrusted clients

Known Limitations

• Mac must be awake + on Tailscale. If the Mac sleeps or goes offline, delegations timeout.

• Session lifetime depends on Claude process. If Claude restarts (Mac reboot, crash), session IDs are lost.

• bridge.log grows unbounded. No log rotation, monitor size or add your own.

• Async server, concurrent tool calls are supported but each delegation opens its own SSH connection to the Mac.

• --dangerously-skip-permissions is hardcoded. If you want to review permissions per-call, fork and modify.

License

MIT.

Trust boundary

By default the bridge runs Claude Code under the Mac's own permission configuration. Setting CLAUDE_BRIDGE_SKIP_PERMISSIONS=true removes that layer: any agent that can call this MCP tool then has arbitrary code execution on the Mac. Only enable it if the MCP server is reachable exclusively by agents you would hand a shell to.

The audit log (bridge.log) records the full task, context, and response text of every delegation. Treat it as sensitive and leave it out of any repo (it is gitignored here).

Status

What this is: a single-tool MCP server that delegates tasks to Claude Code on one Mac over SSH, with session continuity and an audit log.

What this is NOT: an authentication layer, a sandbox, or a multi-host router. The argument building, output parsing, and log rotation are unit-tested; the SSH path is exercised by supervised live delegations, not CI. This file has a sibling repo, see PORTING.md.