mcp-proxy-bridge
Automatically configures git to use a URL-scoped proxy for specified hosts, allowing git commands (clone, fetch, pull, push, etc.) to work through a local proxy.
Routes traffic to GitHub (and subdomains) through a local proxy, enabling git operations on repositories that would otherwise be unreachable due to network restrictions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-proxy-bridge check if github.com is reachable"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
Probes whether the target is reachable directly.
If not, checks the local proxy port; if closed, launches your proxy client and waits for the port.
Verifies the target through the proxy (HTTP CONNECT or SOCKS5 → TLS HEAD).
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: Claude GPT Launcher
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-bridgeInstall globally (recommended for the hook, which runs on every Bash call)
npm install -g mcp-proxy-bridgeFrom source / GitHub
git clone https://github.com/xiaolaifeng/mcp-proxy-bridge.git
cd mcp-proxy-bridge
node src/server.mjs --print-config # sanity checkQuick start (Claude Code)
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 # verifySee
examples/for Clash Verge, v2rayN, sing-box, and SOCKS5.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-bridgeRegister the hook in
~/.claude/settings.json:{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "mcp-proxy-bridge-hook" } ] } ] } }(Use
npx -y mcp-proxy-bridge-hookinstead if not installed globally, but global install is faster for a per-command hook.)Restart Claude Code. Run a
git pullthat 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 withPROXY_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"] }
}Field | Meaning |
| Hosts to verify. |
| Port probed on each target (443 = HTTPS). |
| Your local proxy address. |
|
|
| Command to start your proxy client. |
| How long to wait for the port after launching. |
| Best-effort process names for |
| Hook sets URL-scoped git proxy for the targets. |
| Override git URL prefixes (defaults to |
| Hook fires when a command mentions any target host. |
| Extra regexes that trigger the hook (default: git network verbs). |
Environment variables
Var | Maps to |
| Config file path. |
| Comma-separated targets. |
| Target port. |
| Proxy endpoint. |
| Launch command (args: JSON array or space-split). |
| Comma-separated process names. |
|
|
| Comma-separated git URL prefixes. |
| Comma-separated extra trigger regexes. |
MCP tools
Tool | Description |
| Check direct; if down, start proxy, wait for port, verify via proxy. |
|
|
| Proxy process running? Port open? Targets? |
| Launch / best-effort kill. |
| Proxy URL + env/git-config hints (and unset). |
| Apply the URL-scoped git proxy. |
| Resolved config + config path. |
Platform notes
Windows: process detection via
tasklist, stop viataskkill. Append.exeautomatically.macOS / Linux: process detection via
pgrep, stop viapkill. Setlaunch.commandto the app binary oropen -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-bridgeThe 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
statusshowsproxyPortOpen: false: your proxy client isn't running or the port differs — checkproxy.portandlaunch.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: falseeven when running: add the rightprocess.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 setPROXY_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 silentSecurity & 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--unsetcommands inproxy_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
Available Tools
8 toolscheckB
Test HTTPS reachability of a target host. useProxy=true routes through the configured proxy; false=direct.
Inputs: target, useProxy.
ensure_accessA
Ensure the target host (default: first configured target) is reachable. Checks direct first; if it fails, launches the proxy, waits for the port, and verifies through the proxy. Returns status + proxy URL.
Inputs: target.
proxy_infoA
Return the proxy URL plus copy-paste hints for HTTPS_PROXY env vars and URL-scoped git config (and how to unset).
Inputs: no named parameters.
set_git_proxyA
Apply the URL-scoped git http proxy for the configured targets (idempotent). Useful after the proxy is up.
Inputs: no named parameters.
show_configA
Return the resolved configuration and the config file path (for debugging).
Inputs: no named parameters.
start_proxyA
Launch the configured proxy client (detached). Returns whether it was launched vs. already running.
Inputs: no named parameters.
statusB
Report whether the proxy process is running (best-effort), the proxy port is open, and the configured targets.
Inputs: no named parameters.
stop_proxyA
Best-effort kill of the configured proxy process(es).
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools have distinct purposes, but 'check' and 'ensure_access' both test reachability; 'ensure_access' is a higher-level operation that may also launch the proxy, causing slight ambiguity.
Tool names use a mix of conventions: some are verbs only ('check'), some are verb_noun ('start_proxy'), and some are noun_only ('status') or noun_info ('proxy_info'), lacking a consistent pattern.
With 8 tools, the set is well-scoped for managing a proxy bridge, covering essential operations without unnecessary bloat.
The tool set covers core proxy lifecycle (start/stop/status), reachability testing, configuration access, and git proxy setup. Missing direct tool for managing proxy targets, but config editing may be external.
Maintenance
Related MCP Connectors
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Security & DLP proxy for MCP: tool-poisoning scans, PII redaction on tool args/results. Beta.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceA proxy server that enables communication between clients (like Claude AI or VS Code) and JetBrains IDEs, allowing AI assistants to access IDE functionality.0-
- AlicenseNot gradedqualityCmaintenanceEnables Codex chat to use the Claude Code harness for repository consultation and editing, routing through GPT models via a local proxy.39 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to securely access authenticated services (HTTP, SSH, SMTP) without exposing secrets, by acting as a server-side proxy that injects authentication.MIT
- FlicenseNot gradedqualityCmaintenanceA zero-config local desktop proxy gateway for AI coding agents, providing model failovers, spend caps, and 1-click MCP tool syncing across multiple client environments.-