maximilianfeix/proxy-scraper

Free proxies that actually work: 700+ sources, every hit verified (honeypots, injected scripts, TLS), a live list every hour, a rotating proxy server and an MCP server for AI agents. - maximilianfe...

33 stars · 6 forks

README

Install · Live list · For AI agents · Proxy server · How it works · Recipes · Options · FAQ

Most free proxy lists are 95 % dead, and a good part of the rest are honeypots or proxies that inject scripts into your pages. proxy-scraper collects public HTTP, SOCKS4 and SOCKS5 proxies from 700+ sources and keeps only the ones that pass every check. It learns with every run which sources are worth it, and it can turn the result into a single rotating proxy. In numbers: in one day it checked 3.6 million free proxies – 1.1 % worked, and more than half of the ones that answered failed a second request. What's actually out there →

Table of contents

Install Live proxy list For AI agents (MCP) Features · Why not just download a list? Examples Recipes Rotating proxy server Discord and Telegram bot How it works Output Options GitHub Actions FAQ Roadmap · Contributing · Community · Acknowledgements

Install With pipx (recommended – gives you a proxy-scraper command in its own environment): pipx install proxy-scraper-cli proxy-scraper The package is called proxy-scraper-cli on PyPI (the plain name is taken), the command is proxy-scraper.

Other ways: Docker, pip, a faster event loop, or straight from the repo

Docker – learned state and results stay in two folders next to you

pip into the current environment

optional: faster event loop on macOS/Linux

the latest main instead of the latest release

no install at all

Started without arguments, a wizard asks what you are looking for:

Preset What it does

Find everything all protocols, maximum yield

Browsing & web HTTP + SOCKS5, HTTPS-capable, at least anonymous, under 3 s

Maximum anonymity elite SOCKS5 with HTTPS only

Fast & stable proxies under 1 s only

A few right now stops after 25 hits

Recheck the last hits no collecting, takes seconds

Proxy server right away recheck the last hits, then serve them on :8899

Same as last time your previous choice

Custom … protocols, countries, anonymity, HTTPS, target site, latency, amount, check mode

Keys: ↑↓ select · Space toggle · 1–9 jump · Enter next · Esc back · q quit. In scripts and cron jobs the wizard never shows up – pass options or -y.

Live proxy list Don't want to scan yourself? Every hour GitHub Actions runs the tool and publishes the hits to the proxy-list branch – every entry worked in the last run, fastest first.

Just want the lists? They also live in a repository of their own, maximilianfeix/free-proxy-list – one list per protocol, per country and per site, updated every hour, with the numbers of the last run on the front page. Watch or star it to keep it at hand.

→ Browse it on the website – search, filter by type, country, HTTPS, provider and latency, see how long each proxy has been up and how often it was on the list this week, copy or download exactly the proxies you need. Every protocol and country also has its own page with a plain download, e.g. SOCKS5 or Germany (country/de/proxies.txt).

List Format Link

All socks5://1.2.3.4:1080 all.txt

HTTP · SOCKS4 · SOCKS5 1.2.3.4:8080 http.txt · socks4.txt · socks5.txt

HTTPS-capable only type://ip:port https.txt

Elite only type://ip:port elite.txt

Gets through to Google · Reddit · Amazon · Instagram · TikTok (no captcha, no block in the last run) type://ip:port google.txt · reddit.txt · amazon.txt · instagram.txt · tiktok.txt

Stable, on the list in 90 %+ of this week's runs type://ip:port stable.txt

With all details latency, country, HTTPS, anonymity, exit IP, uptime, sites proxies.json · proxies.csv

curl -s https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/socks5.txt | head Over time: every day the first run's proxies.json is kept for good as a gzipped asset of the release of that year, like snapshots-2026 – proxies-2026-09-28.json.gz and so on, for anyone who wants to look at free proxies over weeks and months. Every file is also on GitHub Pages, which sits behind a CDN, isn't rate limited like raw.githubusercontent and sends CORS headers, so it works straight from the browser: https://maximilianfeix.github.io/proxy-scraper/socks5.txt. jsDelivr works too, but can lag behind by a few hours. Or let the tool start from it: proxy-scraper --recheck live downloads the list and checks it again from your network – about 30 seconds instead of a full scan (517 of 1,169 worked from here). With --serve you have a rotating proxy in under a minute.

For AI agents (MCP)

proxy-scraper-mcp is an MCP server: Claude Code, Claude Desktop, Cursor, VS Code, Codex and any other MCP client can ask for working proxies and load pages through them.

Tool What it does

get_proxies working proxies right now, from the hourly list – filter by protocol, country, HTTPS, elite, no datacenter, not blocklisted, stable, uptime, latency, gets through to Google/Reddit/Amazon

check_proxies checks proxies from your own network, so they work from where your code runs (30–90 s, reports progress)

fetch_url loads a page through a verified proxy, switches proxies by itself when one fails, returns readable text – HTTPS only through proxies with verified TLS

Things to ask your agent: "Load bbc.com/news as seen from the UK", "Give me 5 SOCKS5 proxies from Germany that aren't in a datacenter", "Check which of these sites block free proxies". Needs uv – it fetches a suitable Python by itself if yours is older than 3.10. Claude Code: claude mcp add proxy-scraper -- uvx --python ">=3.10" --from "proxy-scraper-cli[mcp]" proxy-scraper-mcp Claude Desktop, Cursor and most other clients – add this to the MCP config (Claude Desktop: Settings → Developer → Edit Config, Cursor: ~/.cursor/mcp.json): { "mcpServers": { "proxy-scraper": { "command": "uvx", "args": ["--python", ">=3.10", "--from", "proxy-scraper-cli[mcp]", "proxy-scraper-mcp"] } } }

VS Code, Codex, or without uv VS Code – .vscode/mcp.json: { "servers": { "proxy-scraper": { "type": "stdio", "command": "uvx", "args": ["--python", ">=3.10", "--from", "proxy-scraper-cli[mcp]", "proxy-scraper-mcp"] } } } Codex – ~/.codex/config.toml: [mcp_servers.proxy-scraper] command = "uvx" args = ["--python", ">=3.10", "--from", "proxy-scraper-cli[mcp]", "proxy-scraper-mcp"] Without uv: pipx install --python python3.12 "proxy-scraper-cli[mcp]" (any Python 3.10+), then use proxy-scraper-mcp as the command. It's also in the official MCP registry as io.github.maximilianfeix/proxy-scraper, so clients that browse the registry can install it from there.

The server tells agents what it tells you: free proxies are run by strangers, so no logins, cookies or personal data through them. Local and private addresses are refused, and results go to proxy-scraper's data folder, not into the project you're working in.

Features

Setup wizard Started without arguments, the tool asks what you need using the arrow keys – a preset or step by step. At the end it shows the matching command line.

Fast 700+ sources fetched in parallel, large lists parsed on all CPU cores, hand-written HTTP/SOCKS handshakes directly on asyncio with 2000+ checks at once.

Real verification Every hit has to fetch two independent pages – that weeds out honeypots that only answer check requests (in some runs 5 out of 6 “hits”). A third request catches proxies that tamper with content: in our measurements one in five working proxies injected a script into a plain HTML page. Plus: HTTPS through a tunnel with verified TLS, anonymity level elite / anonymous / transparent and the country of the exit IP.

Learns with every run Hit rate per source, history of working proxies, automatic removal of dead and stale lists. With -l 5000 you get the best 5000 candidates, not just any.

Finds new sources by itself Searches GitHub for actively maintained proxy lists and reads source lists maintained by others. Spam clone farms and plain mirrors are detected.

Filters & target sites With --target google.com a proxy only counts if it really reaches the site – many public proxies are blocked by Google, Discord & co. Filter by country, HTTPS, anonymity and latency, and stop with --want 50 as soon as enough matching proxies are found. Filters even speed things up: with --max-latency 1000 slow proxies are given up after 1 s instead of 8 s.

Live dashboard Speed chart, latency histogram, protocols, countries and the latest hits in real time. Ctrl+C stops at any time and saves everything.

Rotating proxy server --serve turns the hits into a local proxy that sends every connection through a different one – with automatic failover when one hangs.

Runs everywhere macOS, Linux and Windows, Python 3.9 to 3.13. Only two dependencies: rich and certifi. It even notices when a firewall blocks proxies.

Thoroughly tested 450+ tests run offline against real mini proxies and honeypots on localhost – on Linux, macOS and Windows with Python 3.9, 3.11 and 3.13.

Why not just download a list?

Typical proxy list repo proxy-scraper

Proxies checked right before you use them ❌ ✅

Honeypots that fake a successful check filtered out ❌ ✅

Proxies that inject scripts or ads filtered out ❌ ✅

HTTPS tested with verified TLS rarely ✅

Anonymity level and country per proxy sometimes ✅

Only proxies that reach your target site ❌ ✅ --target

Learns which sources are worth it ❌ ✅

Usable as a single rotating proxy ❌ ✅ --serve

API to fetch a proxy (proxy_pool compatible) ❌ ✅ /get

Ready-made list without running anything ✅ ✅ live list

Examples

50 proxies that can do HTTPS – then stop

only Germany, Austria and Switzerland, the 20,000 most promising candidates

fast elite SOCKS5 proxies

20 proxies that really reach Google AND Discord

only recheck the last hits (plus history) – takes seconds

wizard with defaults – it keeps what you already passed

which sources deliver the most?

From Python from proxyscraper import check_proxies, find_proxies

if _name_ == "_main_": # needed on macOS/Windows, the parser uses a process pool for p in find_proxies(want=20, https=True, countries=["DE", "NL"], no_datacenter=True): print(p.url, p.latency, p.country, p.org)

alive = check_proxies(["socks5://1.2.3.4:1080", "5.6.7.8:3128"]) # your own list Same run as the command line – sources, learning, every check, result files – just without terminal output. Each result has url, latency, exit_ip, https, anonymity, country, asn, org and hosting. There's an async version of both (find_proxies_async, check_proxies_async). Don't need a fresh scan? live_proxies takes the live list instead – no checks, one download, done in about a second: import itertools, requests from proxyscraper import live_proxies

proxies = live_proxies(types=["socks5"], https=True, min_uptime=90) # the reliable ones this week pool = itertools.cycle(p.url for p in proxies) r = requests.get("https://api.ipify.org", proxies={"https": next(pool)}, timeout=15) # pip install "requests[socks]" Same filters as find_proxies, plus min_uptime, works_on (["google"], "reddit", "amazon", "instagram", "tiktok") and limit. Every result also has uptime_24h, uptime_7d, first_seen, up_for_hours and sites. Or let the library do the retrying: ProxyRotator loads a URL through the list and moves on to the next proxy when one fails – HTTPS only through proxies with verified TLS. from proxyscraper import ProxyRotator

with ProxyRotator(country="DE") as rotator: r = rotator.get("https://httpbin.org/ip") print(r.status, r.text, "via", r.via) Usually a few seconds; when many proxies in a row are down it can take a minute (timeout= is per attempt). There's aget() with async with for asyncio code. Already using requests, httpx, Playwright or Scrapy? proxy_url() gives you one local proxy address that rotates behind the scenes – every connection goes out through another proxy from the list, best first, dead ones skipped: import requests from proxyscraper import ProxyRotator

with ProxyRotator(country="DE") as rotator: proxy = rotator.proxy_url() # http://country-de:…@127.0.0.1:… requests.get("https://api.ipify.org", proxies={"http": proxy, "https": proxy}) # httpx.Client(proxy=proxy) · scrapy: meta={"proxy": proxy} · curl -x "$proxy" # Playwright wants the login apart: chromium.launch(proxy=rotator.playwright_proxy()) It runs on 127.0.0.1 with a random password, takes over each new hourly list by itself and stops with the with block.

Rotating proxy server A list is nice – but usually you just want to enter one proxy that always works: proxy-scraper --recheck --serve # recheck the last hits, then go – takes seconds curl -x http://127.0.0.1:8899 https://api.ipify.org # a different IP every time curl -x socks5h://127.0.0.1:8899 https://api.ipify.org # SOCKS5 on the same port curl -x http://country-de:x@127.0.0.1:8899 https://api.ipify.org # only German exits curl -x http://session-cart42:x@127.0.0.1:8899 https://shop.example # same proxy for this session curl http://127.0.0.1:8899/__proxy-scraper/status # pool and counters as JSON curl http://127.0.0.1:8899/__proxy-scraper/metrics # the same for Prometheus/Grafana Like commercial rotating proxies, the username carries what you want: country-XX, type-http|socks4|socks5 and session-NAME, combinable (country-us-type-socks5-session-a). It works for HTTP (Proxy-Authorization) and SOCKS5 (username/password auth). By default the password is ignored and the server only listens on 127.0.0.1. To reach it from other machines, give it a password – every client then has to send it, over HTTP and SOCKS5 alike, and the status page wants it as Basic auth: export PROXY_SCRAPER_SERVE_PASSWORD=$(openssl rand -hex 16) # the env var keeps it out of `ps` proxy-scraper --recheck --serve --serve-host 0.0.0.0 curl -x "http://country-de:$PROXY_SCRAPER_SERVE_PASSWORD@your-server:8899" https://api.ipify.org Without a password, --serve-host means anyone who reaches the port can use it. The ready-made compose.yaml starts the server in Docker from the live list, with a password, a health check and learned state in a volume: put PROXY_PASSWORD=… into .env, then docker compose up -d.

Option What it does

--rotate weighted default: fast and proven proxies more often, everyone gets a chance

--rotate random / round-robin evenly, at random or in turn

--rotate fastest always the fastest one that isn't busy

--sticky 300 the same site keeps its proxy for 5 minutes (logins, carts)

every connection goes through a different proxy (unless sticky); fast and proven ones are preferred CONNECT for HTTPS and plain HTTP requests; HTTP, SOCKS4 and SOCKS5 proxies can sit behind it (SOCKS5 with DNS through the proxy) HTTPS only uses proxies that passed the test with verified TLS – no broken encryption if a proxy stays silent inside the tunnel or returns an error page instead of TLS, the same first packet quietly goes to the next one three failures in a row and a proxy leaves the rotation – every 5 minutes those get re-checked and come back if they work again --serve-refill 6 checks fresh proxies every 6 hours in the background (the live list with --recheck live, otherwise the last run + history) with the same checks and filters, and adds the hits – a server that runs for days doesn't run dry listens on 127.0.0.1 only (unless --serve-host says otherwise), optionally with a password; live view with requests, success rate, pool and the latest connections

In testing: 20 of 20 HTTPS requests succeeded, over 15 different exit IPs. In the wizard this is Proxy server right away.

Proxy pool API Some programs want a proxy address, not a proxy – to hand it to a browser, a worker or a queue. The same port answers plain HTTP requests with one: curl http://127.0.0.1:8899/get # one proxy as JSON, chosen like a connection would be curl "http://127.0.0.1:8899/get?country=DE&https=1&format=txt" # → http://203.0.113.7:8080 curl "http://127.0.0.1:8899/all?protocol=socks5&limit=20" # the 20 best SOCKS5 proxies curl "http://127.0.0.1:8899/report?proxy=203.0.113.7:8080&ok=0" # it failed you – three times and it's out

Endpoint What it does

/get one proxy, picked by the --rotate strategy

/pop like /get, and the proxy leaves the pool

/all every usable proxy, best first (limit=N)

/count totals by type and country

/delete?proxy=IP:PORT take a proxy out

/report?proxy=IP:PORT&ok=0 feedback from your own requests

Filters work on /get, /pop and /all: country=DE,AT, protocol=socks5, https=1, anonymity=elite, max_latency=1500, and format=txt for plain URLs. With --serve-password the API wants it as Basic auth, like the status page. Coming from jhao104/proxy_pool? The endpoints, type=https and the JSON fields (proxy, https, region, anonymous, check_count, fail_count, …) are the same, so point your code at port 8899 and it keeps working – without Redis, and with proxies that passed the honeypot, tampering and TLS checks: import requests proxy = requests.get("http://127.0.0.1:8899/get?type=https").json()["url"] # e.g. socks5://…, type included requests.get("https://example.com", proxies={"http": proxy, "https": proxy})

Discord and Telegram bot The live list can also come to you: bot/ is a Discord bot that posts every run into a server – a summary with the fastest proxies, the full lists per protocol as files, and slash commands like /proxies type:socks5 country:DE https:true. It sets up its own read-only channels when you invite it, and a GitHub Action deploys it to a server as a systemd service. The same process answers on Telegram too: /proxy de socks5 for one proxy with a curl line, /proxies 10 us https for a short list. Setup in bot/README.md.

How it works

flowchart LR A[sources.json<br/>meta lists<br/>GitHub discovery] --> B[Fetch & parse<br/>in parallel on all cores] B --> C[Prioritize<br/>history → good sources → rest] C --> D[Check<br/>HTTP · SOCKS4 · SOCKS5] D -->

source