claude-mac-bridge

MCP server that lets an AI agent delegate tasks to Claude Code running on a remote Mac over SSH or Tailscale. It returns structured output with a reusable session ID.

How it works

Agent → ask_claude → SSH → Claude Code on the Mac → response + session_id

The bridge runs Claude Code non-interactively with claude -p, parses its JSON response, and records each delegation in a local audit log.

When this is useful

Use the bridge when your main agent or UI runs on another machine, but the code, toolchain, and authenticated Claude Code installation live on your Mac. One MCP call moves the coding task into that environment without manual SSH commands, prompt escaping, JSON parsing, or session bookkeeping.

Pass the returned ID back as resume_session_id for related work. Claude resumes the saved conversation, decisions, and task context while the worktree stays on the Mac.

Requirements

• Claude Code installed and signed in on the Mac
• Passwordless SSH from the agent machine to the Mac
• Python 3.10+ on the agent machine
• Tailscale on both machines, if the Mac is reached through Tailscale
• GNU timeout on the Mac for remote process cleanup (brew install coreutils)

Setup

1. Prepare Claude Code on the Mac

curl -fsSL https://claude.ai/install.sh | bash
claude  # follow the sign-in prompt
claude -p "what is 2+2" --output-format json

2. Prepare SSH on the agent machine

ssh-keygen -t ed25519 -f ~/.ssh/mac_bridge
ssh-copy-id -i ~/.ssh/mac_bridge.pub user@<mac-tailscale-ip>
ssh -i ~/.ssh/mac_bridge user@<mac-tailscale-ip> "claude --version"

3. Connect your agent

git clone https://github.com/freeze1999/claude-mac-bridge.git
cd claude-mac-bridge
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

BRIDGE_DIR="$PWD"
codex mcp add claude_bridge \
  --env CLAUDE_BRIDGE_SSH_HOST="[email protected]" \
  --env CLAUDE_BRIDGE_CLAUDE_BIN="/opt/homebrew/bin/claude" \
  -- "$BRIDGE_DIR/.venv/bin/python" "$BRIDGE_DIR/server.py"

Run codex mcp list, restart Codex, then use /mcp to confirm the server is active. The agent discovers ask_claude from the server automatically. For calls longer than Codex's default MCP tool timeout, add tool_timeout_sec = 620 under [mcp_servers.claude_bridge] in ~/.codex/config.toml.

Claude Code can register the same STDIO server with its own MCP command:

BRIDGE_DIR="/absolute/path/to/claude-mac-bridge"
claude mcp add --transport stdio --scope user claude_bridge \
  -e CLAUDE_BRIDGE_SSH_HOST="[email protected]" \
  -e CLAUDE_BRIDGE_CLAUDE_BIN="/opt/homebrew/bin/claude" \
  -- "$BRIDGE_DIR/.venv/bin/python" "$BRIDGE_DIR/server.py"

Tool usage

# Run in a specific project on the Mac
r1 = ask_claude(
    task="Fix the failing tests",
    workdir="/Users/me/projects/app",
)

# Continue the same Claude conversation
r2 = ask_claude(
    task="Now simplify the implementation",
    workdir="/Users/me/projects/app",
    resume_session_id="<session_id from r1>",
)

ask_claude accepts:

Configuration

Monitoring

python3 monitor.py
python3 monitor.py /path/to/bridge.log

Trust boundary

Claude Code's permission configuration controls what delegated tasks may do on the Mac. Setting CLAUDE_BRIDGE_SKIP_PERMISSIONS=true removes that layer for every caller of this bridge. The audit log contains complete task and response text and is gitignored by default.

Status

The bridge supports remote working directories, structured Claude output, session recovery, concurrent calls, audit logging, and log rotation.

Argument building, JSON parsing, working-directory handling, and log rotation are unit-tested. New and resumed Claude sessions are also exercised with live CLI runs.

License

MIT.