proxy-finder-mcp

An MCP (Model Context Protocol) server that finds and validates working free HTTP/HTTPS/SOCKS proxies, optionally filtered by country. Built for agents that need to route a request or curl through a specific country — a geo-blocked municipal site, a region-locked API, or just debugging why a request fails from one network but not another.

It aggregates three free proxy-list sources (ProxyScrape, Proxifly, Geonode), merges and dedupes them, and actually tests candidates live (not just trusting self-reported uptime) before handing one back — with a local disk cache so repeat calls don't re-scrape or re-test everything from scratch.

Pure TypeScript, zero external process dependencies (no curl/ffmpeg/etc. required) — works anywhere Node.js does, install-free via npx.

Install

No install step needed — run it directly with npx. Add it to your MCP client's config:

Claude Code

claude mcp add proxy-finder -- npx -y proxy-finder-mcp

Claude Desktop / other JSON-config clients

Add to your MCP config file (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "proxy-finder": {
      "command": "npx",
      "args": ["-y", "proxy-finder-mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "proxy-finder": {
      "command": "npx",
      "args": ["-y", "proxy-finder-mcp"]
    }
  }
}

Google Antigravity

Open the Manage MCP Servers panel (Command Palette → "MCP") and add a new server, or edit its mcp_config.json directly with the same mcpServers block used above:

{
  "mcpServers": {
    "proxy-finder": {
      "command": "npx",
      "args": ["-y", "proxy-finder-mcp"]
    }
  }
}

Related MCP server: klawfetch

Tools

find_proxy parameters

Example

"I need a working proxy in France to check if this site is geo-blocked."

The agent calls find_proxy with { "country": "FR" } and gets back something like:

{
  "found": true,
  "proxy": {
    "proxy": "socks4://31.59.234.26:40001",
    "ip": "31.59.234.26",
    "port": 40001,
    "protocol": "socks4",
    "countryCode": "FR",
    "city": "Amiens",
    "latencyMs": 1918,
    "statusCode": 200,
    "testUrl": "https://httpbin.org/ip"
  },
  "alternates": [ ... ],
  "testedCount": 25,
  "candidatePoolSize": 225
}

How it works

1. Sources — ProxyScrape v4, Proxifly's static list, and Geonode's proxy-list API are fetched concurrently and merged, deduped by ip:port. The merged list is cached on disk for 10 minutes so repeat tool calls don't hammer any source.

2. Ranking — before live-testing, candidates are sorted cache-first: previously-confirmed fast proxies come first (fastest first), then untested proxies (best self-reported uptime/speed first), then previously-failed proxies last.

3. Validation — a capped, concurrency-bounded batch of ranked candidates is dialed for real (via axios + https-proxy-agent/socks-proxy-agent — no shelling out to curl) against a target URL. Success = the request completes with an HTTP status in [200, 400).

4. Caching — every tested proxy's result (success and failure) is written to ~/.proxy-finder-mcp/health.json with a timestamp, so later calls skip re-testing recently confirmed-fast or confirmed-dead proxies.

Local development

git clone https://github.com/shakthizen/proxy-finder-mcp.git
cd proxy-finder-mcp
npm install
npm run build
npm run typecheck
npm run lint
npm test
node dist/index.js   # runs the server over stdio

License

MIT © shakthizen