Proxy Doctor

[proxy-doctor logo]

proxy-doctor

[PyPI] [License] [Platform] [Python] [GitHub Stars]

Diagnose proxy misconfigurations that break AI coding tools.

When your browser works fine but Cursor / VS Code / Windsurf AI features don't — proxy-doctor tells you exactly why and how to fix it.

The Problem

AI coding tools (Cursor, VS Code with Copilot, Windsurf) rely on long-lived streaming connections (SSE/HTTP2) that break when:

• Your system proxy points to a localhost port where nothing is listening
• A VPN/proxy app was closed but its settings linger in macOS system preferences
• Your editor inherited stale proxy environment variables from launchctl
• The proxy is running but buffers streaming responses, breaking AI completions

The result: "browser works, AI editor doesn't" — the most common and frustrating developer experience.

What It Checks

proxy-doctor inspects 5 layers of your macOS proxy configuration:

Quick Start

CLI

# Installpip install proxy-doctor
# Run diagnosis (JSON output — default, optimized for AI agents)proxy-doctor check
# Run diagnosis (human-readable output)proxy-doctor check --human
# Show recommended fixesproxy-doctor fix
# Check a different editorproxy-doctor check --editor vscode

As an MCP Tool (for AI agents)

proxy-doctor ships as an MCP server that AI agents can call directly:

# Install with MCP supportpip install proxy-doctor[mcp]
# Run MCP serverpython -m proxy_doctor.mcp_server

Add to your MCP configuration (e.g., Cursor ~/.cursor/mcp.json):

{  "mcpServers": {    "proxy-doctor": {      "command": "python3",      "args": ["-m", "proxy_doctor.mcp_server"]    }  }}

Note: "command" must point to the Python where proxy-doctor[mcp] is installed. If python3 doesn't work, use the full path (run which python3 or python3 -c "import sys; print(sys.executable)" to find it).

Your AI agent can then call:

• diagnose_proxy(editor="cursor") — full 5-layer diagnosis with evidence
• list_fixes(editor="cursor") — recommended fixes with executable commands
• supported_editors() — list available editors

For AI Agents: Quick Install

One-liner (paste this to your AI agent):

Install proxy-doctor (pip install proxy-doctor[mcp]) and add it to your MCP config with command python -m proxy_doctor.mcp_server. Then use the diagnose_proxy tool to check proxy health.

If you are an AI agent setting up proxy-doctor for your user:

# 1. Installpip install proxy-doctor[mcp]
# 2. Find the Python pathpython3 -c "import sys; print(sys.executable)"
# 3. Add to ~/.cursor/mcp.json (use the path from step 2)# {#   "mcpServers": {#     "proxy-doctor": {#       "command": "<python-path-from-step-2>",#       "args": ["-m", "proxy_doctor.mcp_server"]#     }#   }# }
# 4. If MCP is not available, use CLI directly (zero dependencies):proxy-doctor check          # JSON outputproxy-doctor check --human  # human-readableproxy-doctor fix            # show fixes (read-only)proxy-doctor fix --apply    # apply fixes (asks for confirmation)

Daemon Mode (v0.2+)

Run proxy-doctor as a persistent background service with automatic health monitoring:

# Start daemon (installs as macOS launchd service)proxy-doctor daemon start
# Check daemon statusproxy-doctor daemon status
# Stop daemonproxy-doctor daemon stop
# Check for updatesproxy-doctor update

The daemon runs every 5 minutes, compares results with the previous check, and sends a macOS notification when status changes (e.g. healthy → unhealthy).

Menu Bar (SwiftBar)

# If SwiftBar is installedcp plugins/swiftbar/proxy-doctor.5m.sh ~/Library/Application\ Support/SwiftBar/Plugins/chmod +x ~/Library/Application\ Support/SwiftBar/Plugins/proxy-doctor.5m.sh

Shows a green/red/orange indicator in your menu bar with one-click diagnosis.

Example Output

Unhealthy (Case A: dead proxy port)

{  "status": "unhealthy",  "diagnosis": {    "case": "A",    "root_cause": "Editor is configured to use proxy at 127.0.0.1:10903, but no process is listening on that port.",    "confidence": "high",    "source": "system proxy (Wi-Fi (http))",    "browser_explanation": "Browser may use a different proxy path (e.g. browser-only mode) or fall back to a direct connection."  },  "fixes": [    {      "fix_id": "clear-system-http-wi-fi",      "description": "Disable http proxy on Wi-Fi",      "command": "networksetup -setwebproxystate \"Wi-Fi\" off",      "risk": "low"    }  ]}

Healthy

proxy-doctor v0.2.0Editor: cursor | Platform: Darwin
Status: HEALTHY
No proxy contamination detected.

Supported Editors

How It Works

proxy-doctor identifies three failure patterns:

Case A — Dead proxy port (high confidence): Your system or editor points to 127.0.0.1:port but nothing is listening. This happens when a VPN/proxy app is closed but its settings remain.

Case B — Streaming broken (medium confidence): A proxy is running, but it buffers SSE/streaming connections that AI editors depend on. Common with browser-only proxy modes.

Case C — Path mismatch (medium confidence): Browser and editor use different proxy paths. Browser works via a dedicated proxy route; editor inherits a stale or incompatible one.

Platform Support

• macOS: Full support (system proxy, launchctl, networksetup)
• Linux: Partial (editor config + environment variables; no networksetup)
• Windows: Not yet supported

Trust & Permissions

proxy-doctor follows a read-only by default design. No system changes are made unless you explicitly opt in.

Default Behavior (read-only)

Opt-in Fix Application

proxy-doctor fix shows the recommended commands but does not execute them.

To apply fixes, use proxy-doctor fix --apply:

• Each fix is shown with its command and risk level
• You are prompted individually for each fix ([y/N])
• Default is No — nothing runs unless you type y
• You can abort at any time with Ctrl+C

This two-step model lets AI agents safely call list_fixes() via MCP to see what needs fixing, then present the commands to users for approval.

Feedback

Found a bug? Have a suggestion? Diagnosis didn't help?

• GitHub Issues: https://github.com/Jiansen/proxy-doctor/issues/new
• For AI agents: The JSON output includes a feedback.report_issue URL — include the full JSON when filing issues.

For AI agents providing feedback programmatically (zero dependencies):

# Create a GitHub issue via CLI (requires gh)proxy-doctor check | gh issue create --repo Jiansen/proxy-doctor \  --title "Diagnosis report: [describe issue]" --body-file -
# Or simply: copy the JSON output into a new issue at# https://github.com/Jiansen/proxy-doctor/issues/new

Development

git clone https://github.com/Jiansen/proxy-doctor.gitcd proxy-doctor
# Install in development modepip install -e ".[dev,mcp]"
# Run testsmake test
# Run lintermake lint

If proxy-doctor helped you fix a proxy issue, consider giving it a star on GitHub — it helps others discover the tool.

[Star on GitHub]

License

MIT