webshare-proxy-mcp

An MCP server that routes HTTP requests through Webshare proxies, with exit-IP verification, rotation, and environment hardening.

Features

• Proxy rotation — pick a random or country-filtered proxy from a Webshare account (direct or backbone mode)

• Exit-IP verification — confirm the IP a proxy presents before relying on it

• Strict proxy routing — fetch_via_proxy never falls back to a direct connection

• Environment hardening — generate a permission-restricted (0600) env file exporting standard proxy variables

Related MCP server: Novada Proxy

Requirements

• Python 3.10+

• A Webshare account with an API key (Dashboard → API → Key)

Installation

uv tool install webshare-proxy-mcp

Or run ad-hoc from source:

uv run server.py

Configuration

Tools

Client configuration

Claude Desktop / Claude Code

{
  "mcpServers": {
    "webshare-proxy": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/bayramlcm/webshare-proxy-mcp", "webshare-proxy-mcp"],
      "env": { "WEBSHARE_API_KEY": "YOUR_KEY" }
    }
  }
}

opencode

{
  "mcp": {
    "webshare-proxy": {
      "type": "local",
      "command": ["uvx", "--from", "git+https://github.com/bayramlcm/webshare-proxy-mcp", "webshare-proxy-mcp"],
      "environment": { "WEBSHARE_API_KEY": "YOUR_KEY" }
    }
  }
}

Usage

Via MCP tools:

get_proxy(country_codes="FR")
→ { "proxy_url": "http://user:pass@host:port", "curl_snippet": "curl -x ... https://api.ipify.org", ... }

test_proxy(host, port, username, password)
→ { "ok": true, "status_code": 200, "exit_ip": "82.23.57.191" }

fetch_via_proxy("https://api.ipify.org", host, port, username, password)
→ { "status_code": 200, "headers": { ... }, "body": "82.23.57.191" }

From a shell, using the generated env file:

source /tmp/proxyrc; curl -s https://api.ipify.org
curl -s -x "$PROXY_URL" https://api.ipify.org

Note: exported variables do not survive shell resets between commands. Source the env file on the same command line as the request, or pass the proxy explicitly per request.

Security

• The API key is read from the environment only; never commit credentials.

• write_proxyrc creates files with 0600 permissions because they contain proxy credentials.

• Raw TCP/ICMP tools (nmap, ping) do not honor HTTP proxy settings; use a proxy chaining tool if needed.

• Only access targets you are authorized to access.

License

MIT