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

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="[email protected]"
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: "[email protected]"
      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.