mcp-proxy-bridge

An MCP server + Claude Code hook that makes a target host (e.g. github.com) reachable through your local proxy — launching the proxy client if needed and configuring your tools to route through it.

If you're behind a network where GitHub (or another host) only works through a local proxy like Clash / Clash Verge / v2rayN / sing-box, this bridge makes it just work for your AI coding assistant:

• MCP server — tools to check reachability, start/stop the proxy, and orchestrate the whole flow.

• PreToolUse hook — fires automatically on Bash commands that touch a configured host, brings the proxy up, and points git at it.

Zero dependencies (Node stdlib only) — deliberately, because a tool that fixes network problems must not need a network install.

How it works

Most local proxies run with system proxy and TUN off, so simply starting the proxy client doesn't route your traffic. The bridge:

1. Probes whether the target is reachable directly.

2. If not, checks the local proxy port; if closed, launches your proxy client and waits for the port.

3. Verifies the target through the proxy (HTTP CONNECT or SOCKS5 → TLS HEAD).

4. Sets a URL-scoped git proxy so only the configured host routes through the proxy — every other repo host is untouched. Idempotent and reversible.

Note: this is a local tool. It launches your proxy client and configures your machine. Each user runs their own copy next to their own proxy — it is not a shared hosted service.

Related MCP server: agnt

Install

Use without installing (npx)

# MCP server (spawned once by your client at startup — npx is fine here)
claude mcp add proxy-bridge -- npx -y mcp-proxy-bridge

Install globally (recommended for the hook, which runs on every Bash call)

npm install -g mcp-proxy-bridge

From source / GitHub

git clone https://github.com/xiaolaifeng/mcp-proxy-bridge.git
cd mcp-proxy-bridge
node src/server.mjs --print-config   # sanity check

Quick start (Claude Code)

1. Create a config (edit the result to match your proxy client):

   mcp-proxy-bridge --init            # writes ~/.mcp-proxy-bridge.json
   $EDITOR ~/.mcp-proxy-bridge.json   # set launch.command, ports, process.names
   mcp-proxy-bridge --print-config    # verify

   See examples/ for Clash Verge, v2rayN, sing-box, and SOCKS5.

2. Register the MCP server (user scope = all projects):

   claude mcp add proxy-bridge --scope user -- npx -y mcp-proxy-bridge
   # or, if installed globally:
   claude mcp add proxy-bridge --scope user -- mcp-proxy-bridge

3. Register the hook in ~/.claude/settings.json:

   {
     "hooks": {
       "PreToolUse": [
         {
           "matcher": "Bash",
           "hooks": [
             { "type": "command", "command": "mcp-proxy-bridge-hook" }
           ]
         }
       ]
     }
   }

   (Use npx -y mcp-proxy-bridge-hook instead if not installed globally, but global install is faster for a per-command hook.)

4. Restart Claude Code. Run a git pull that touches GitHub — the proxy comes up automatically.

Configuration

Config is layered, later wins: defaults < JSON file < environment variables.

• File: ~/.mcp-proxy-bridge.json (override path with PROXY_BRIDGE_CONFIG).

• Env: see table below.

• CLI: --print-config, --init [path].

{
  "targets": ["github.com", "api.github.com", "raw.githubusercontent.com"],
  "checkPort": 443,
  "proxy": { "host": "127.0.0.1", "port": 7897, "scheme": "http" },
  "launch": { "command": "clash-verge", "args": [], "cwd": null, "waitPortMs": 40000 },
  "process": { "names": ["clash-verge", "verge-mihomo", "mihomo"] },
  "gitProxy": { "enable": true, "scope": null },
  "hook": { "matchTargets": true, "extraPatterns": ["\\bgit\\s+[^|;&\\n]*\\b(clone|fetch|pull|push|ls-remote|submodule)\\b"] }
}

Environment variables

MCP tools

Platform notes

• Windows: process detection via tasklist, stop via taskkill. Append .exe automatically.

• macOS / Linux: process detection via pgrep, stop via pkill. Set launch.command to the app binary or open -a "Clash Verge" on macOS.

• Port readiness is the primary "proxy is up" signal on all platforms.

Other MCP clients

Works with any MCP-capable client that speaks stdio (Claude Desktop, etc.). Point the client at:

npx -y mcp-proxy-bridge

The hook is Claude-Code-specific (PreToolUse). For other clients, call the ensure_access tool before GitHub operations, or use the git-proxy hint from proxy_info.

Troubleshooting

• status shows proxyPortOpen: false: your proxy client isn't running or the port differs — check proxy.port and launch.command.

• Proxy up but target still unreachable: the selected node/subscription in your proxy client can't reach the target — switch nodes, then retry.

• processRunning: false even when running: add the right process.names (this field is best-effort; the port probe is authoritative).

• Don't want the persistent git proxy: run git config --global --unset http.<scope>.proxy, or set PROXY_BRIDGE_SET_GIT_PROXY=0.

• If you enable TUN or system proxy in your client, the explicit git proxy becomes unnecessary but stays harmless.

Manual testing

mcp-proxy-bridge --print-config
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'$'\n''{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | node src/server.mjs
echo '{"tool_input":{"command":"git pull origin main"}}' | node src/hook.mjs   # should emit context
echo '{"tool_input":{"command":"docker ps"}}' | node src/hook.mjs             # should be silent

Security & notes

• The bridge only ever talks to 127.0.0.1 (your proxy) and the configured target hosts over TLS. No telemetry, no remote calls.

• set_git_proxy / the hook modify global git config (http.<scope>.proxy) — reversible via the --unset commands in proxy_info.

• MIT licensed.

For maintainers — publishing

npm:

npm version patch         # or minor / major
npm pack                  # inspect the tarball contents
npm publish               # publishes the files listed in package.json "files"

Before publishing, fill in package.json author, repository, homepage, bugs (already set: author Robin Lee, repo xiaolaifeng/mcp-proxy-bridge).

GitHub: push the repo, then users can npx github:xiaolaifeng/mcp-proxy-bridge.

MCP directories (for discovery): submit to mcp.so, Glama, Smithery, and the Anthropic MCP server list.

License

MIT