Skip to content
Back to search

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/maximilianfeix/proxy-scraper with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/maximilianfeix/proxy-scraper'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/maximilianfeix--proxy-scraper/badge.svg)](/listings/maximilianfeix--proxy-scraper)

HTML

<a href="/listings/maximilianfeix--proxy-scraper"><img src="/api/listings/maximilianfeix--proxy-scraper/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**With [pipx](https://pipx.pypa.io/)** (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`.

**With [Homebrew](https://brew.sh)** on macOS and Linux:

brew install maximilianfeix/tap/proxy-scraper

The formula follows each release within about a day.

<details> <summary><b>Other ways: Docker, pip, a faster event loop, or straight from the repo</b></summary> <br>

# Docker – learned state and results stay in two folders next to you
mkdir -p proxy-data results
docker run --rm --user "$(id -u):$(id -g)" -v "$PWD/proxy-data:/data" -v "$PWD/results:/work/results" \
  ghcr.io/maximilianfeix/proxy-scraper --want 50 --https-only

# pip into the current environment
pip install proxy-scraper-cli

# optional: faster event loop on macOS/Linux
pipx install "proxy-scraper-cli[fast]"

# the latest main instead of the latest release
pipx install git+https://github.com/maximilianfeix/proxy-scraper.git

# no install at all
git clone https://github.com/maximilianfeix/proxy-scraper.git
cd proxy-scraper
pip install -r requirements.txt
python3 proxy_scraper.py

Every [release](https://github.com/maximilianfeix/proxy-scraper/releases/latest) also ships a wheel you can install with `pip install <file>.whl`, and a multi-arch image (amd64/arm64) on `ghcr.io`. In the container the wizard never shows up, it runs straight away. For the proxy server use `--serve --serve-host 0.0.0.0` with `-p 127.0.0.1:8899:8899`, so the port is only open on your own machine.

Tab completion for bash, zsh, fish and PowerShell:

eval "$(proxy-scraper --completion zsh)"     # in ~/.zshrc (after compinit), same for bash in ~/.bashrc
proxy-scraper --completion fish > ~/.config/fish/completions/proxy-scraper.fish
proxy-scraper --completion powershell | Out-String | Invoke-Expression   # in $PROFILE

Installed, the learned state lives in your user data folder (`~/Library/Application Support/proxy-scraper`, `%LOCALAPPDATA%\proxy-scraper` or `~/.local/share/proxy-scraper`; override with `PROXY_SCRAPER_HOME`) and results go to `./results`. Run from a clone, both stay inside the project. After the second run that finds proxies it asks once for a GitHub star; `PROXY_SCRAPER_NO_STAR_HINT=1` turns that off (it never shows in CI).

</details>

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

<div align="center"> </div>

| 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: <kbd>↑</kbd><kbd>↓</kbd> select · <kbd>Space</kbd> toggle · <kbd>1</kbd>–<kbd>9</kbd> jump · <kbd>Enter</kbd> next · <kbd>Esc</kbd> back · <kbd>q</kbd> quit. In scripts and cron jobs the wizard never shows up – pass options or `-y`.

<a id="live-list"></a>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 488 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="docs/banner-dark.svg">
  4. <source media="(prefers-color-scheme: light)" srcset="docs/banner-light.svg">
  5. <img src="docs/banner-dark.svg" alt="proxy-scraper – free proxies that actually work" width="100%">
  6. </picture>
  7. **Free HTTP, SOCKS4 and SOCKS5 proxy lists, rebuilt about every hour. A proxy is listed only if it passed the checks of that run, and the result of every check is published with it.**
  8. [![Working proxies](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmaximilianfeix%2Fproxy-scraper%2Fproxy-list%2Fbadges%2Ftotal.json&style=for-the-badge&labelColor=121113)](https://proxy-scraper.de/all.txt)
  9. [![HTTP](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmaximilianfeix%2Fproxy-scraper%2Fproxy-list%2Fbadges%2Fhttp.json&style=for-the-badge&labelColor=121113)](https://proxy-scraper.de/http.txt)
  10. [![SOCKS4](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmaximilianfeix%2Fproxy-scraper%2Fproxy-list%2Fbadges%2Fsocks4.json&style=for-the-badge&labelColor=121113)](https://proxy-scraper.de/socks4.txt)
  11. [![SOCKS5](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmaximilianfeix%2Fproxy-scraper%2Fproxy-list%2Fbadges%2Fsocks5.json&style=for-the-badge&labelColor=121113)](https://proxy-scraper.de/socks5.txt)
  12. [![Updated](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmaximilianfeix%2Fproxy-scraper%2Fproxy-list%2Fbadges%2Fupdated.json&style=for-the-badge&labelColor=121113)](../../actions/workflows/proxy-list.yml)
  13. [![tests](https://github.com/maximilianfeix/proxy-scraper/actions/workflows/tests.yml/badge.svg)](https://github.com/maximilianfeix/proxy-scraper/actions/workflows/tests.yml)
  14. [![PyPI](https://img.shields.io/pypi/v/proxy-scraper-cli?style=flat-square&color=D4F77A&labelColor=121113&label=pypi)](https://pypi.org/project/proxy-scraper-cli/)
  15. [![Downloads](https://img.shields.io/pepy/dt/proxy-scraper-cli?style=flat-square&color=D4F77A&labelColor=121113&label=downloads)](https://pepy.tech/projects/proxy-scraper-cli)
  16. [![Stars](https://img.shields.io/github/stars/maximilianfeix/proxy-scraper?style=flat-square&color=D4F77A&labelColor=121113)](https://github.com/maximilianfeix/proxy-scraper/stargazers)
  17. [![License](https://img.shields.io/badge/license-MIT-D4F77A?style=flat-square&labelColor=121113)](LICENSE)
  18. **English** · [简体中文](README.zh-CN.md) · [Español](README.es.md) · [Deutsch](README.de.md) · [Русский](README.ru.md) · [Português (Brasil)](README.pt-BR.md) · [Français](README.fr.md)
  19. [Website](https://proxy-scraper.de/) · [Benchmark](https://proxy-scraper.de/benchmark/) · [All lists](#live-list) · [Install](#install) · [Python API](#from-python) · [For AI agents](#mcp) · [Proxy server](#proxy-server) · [Discord bot](#discord-bot) · [All docs](docs/README.md)
  20. </div>
  21. ---
  22. ```text
  23. https://proxy-scraper.de/all.txt
  24. https://proxy-scraper.de/http.txt
  25. https://proxy-scraper.de/socks4.txt
  26. https://proxy-scraper.de/socks5.txt
  27. ```
  28. <sub>`http.txt`, `socks4.txt` and `socks5.txt` hold one `ip:port` per line, `all.txt` one `type://ip:port`. Best first, so `head -n 20` gives you the best ones. No signup, no API key, CORS headers included. The badges above are the counts of the last run. The same files are on the [`proxy-list`](../../tree/proxy-list) branch, on [jsDelivr](https://cdn.jsdelivr.net/gh/maximilianfeix/proxy-scraper@proxy-list/) and in a repository of their own, [free-proxy-list](https://github.com/maximilianfeix/free-proxy-list). HTTPS-only, elite, stable, per country, per site, JSON and CSV: [every list](#live-list).</sub>
  29. **Check them from your own network** before you use them. No install needed, `uvx` comes with [uv](https://docs.astral.sh/uv/) (`pipx run` does the same):
  30. ```bash
  31. uvx proxy-scraper-cli --pick 3 --verify # up to 3 proxies from the hourly list that pass right now, from your network
  32. ```
  33. <a id="why-this-list"></a>
  34. ## Why this list
  35. Most free proxy lists on GitHub are long, and most of their entries fail when they are checked. This list is shorter because each run publishes only the proxies that passed. The [benchmark](https://proxy-scraper.de/benchmark/) runs the same checks on the popular lists every hour and shows what share of each one passes:
  36. <a href="https://proxy-scraper.de/benchmark/"><picture>
  37. <source media="(prefers-color-scheme: dark)" srcset="https://proxy-scraper.de/benchmark-dark.svg">
  38. <source media="(prefers-color-scheme: light)" srcset="https://proxy-scraper.de/benchmark-light.svg">
  39. <img src="https://proxy-scraper.de/benchmark-dark.svg" alt="Share of checked proxies that passed every check, per popular free proxy list on GitHub, redrawn about every hour" width="100%">
  40. </picture></a>
  41. <sub>Redrawn about every hour from the hourly runs on a GitHub Actions runner. The date is in the chart. The [benchmark page](https://proxy-scraper.de/benchmark/) has the counts behind each share, how they are measured and why proxy-scraper's own list isn't in it.</sub>
  42. What a proxy on the list has passed, in the last run, from that runner:
  43. | Check | What runs | Required for the list |
  44. |---|---|---|
  45. | `basic` | A handshake (HTTP, SOCKS4 or SOCKS5) and a first request that returns a public exit IP that isn't ours | yes |
  46. | `confirm` | A second request to an unrelated site, which has to see the same exit IP | yes |
  47. | `content` | A static test page over plain HTTP that has to arrive byte for byte as fetched directly | yes |
  48. | `https` | A tunnel to port 443 of one test host with a TLS handshake that verifies | no, recorded per proxy (`https.txt` has the ones that passed) |
  49. Each check ends as `passed`, `failed`, `unavailable` or `skipped`, with a reason code, the target and the time, in `proxies.json`, in the CSV and in the tool's output. A check that didn't run is never shown as passed. Details: [check states](#check-states).
  50. **What a pass doesn't tell you.** Free proxies are run by strangers. Of one run's list, about a quarter was on the list again 24 runs later (median of the week ending 13 Oct 2026). A pass is one measurement, from one network, against test targets: it is not a promise for the next hour or for the site you care about. The HTTPS check is a verified TLS connection to one test host, not a security rating. Use free proxies for public data and testing, never for logins, payments or anything personal. → [What the numbers show and what they don't](docs/free-proxies-in-numbers.md) · [Why free proxies fail](docs/why-free-proxies-fail.md) · [How it compares](docs/comparison.md) · [Who runs free proxies](docs/faq.md#who-runs-free-proxies)
  51. **Used by:** the hourly list is a built-in source of [monosans/proxy-scraper-checker](https://github.com/monosans/proxy-scraper-checker) and [gfpcom/free-proxy-list](https://github.com/gfpcom/free-proxy-list).
  52. <a id="live-list"></a>
  53. ## Live proxy list
  54. About every hour **GitHub Actions** runs proxy-scraper and publishes the hits to the [`proxy-list`](../../tree/proxy-list) branch – every entry passed the first request, the second request and the content check in the last run (the HTTPS test is recorded per entry, not required), best first: fast ones that are likely to still be up come on top.
  55. | List | Format | Link |
  56. |---|---|---|
  57. | All | `socks5://1.2.3.4:1080` | [all.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/all.txt) |
  58. | HTTP · SOCKS4 · SOCKS5 | `1.2.3.4:8080` | [http.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/http.txt) · [socks4.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/socks4.txt) · [socks5.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/socks5.txt) |
  59. | HTTPS-capable only | `type://ip:port` | [https.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/https.txt) |
  60. | Elite only | `type://ip:port` | [elite.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/elite.txt) |
  61. | Gets through to Google · Reddit · Amazon · Instagram · TikTok · Discord (one test request got a normal page in the last run) | `type://ip:port` | [google.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/google.txt) · [reddit.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/reddit.txt) · [amazon.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/amazon.txt) · [instagram.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/instagram.txt) · [tiktok.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/tiktok.txt) · [discord.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/discord.txt) |
  62. | Stable, on the list in 90 %+ of this week's runs | `type://ip:port` | [stable.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/stable.txt) |
  63. | With all details | latency, country, HTTPS, anonymity, exit IP, uptime, sites | [proxies.json](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/proxies.json) · [proxies.csv](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/proxies.csv) |
  64. ```bash
  65. curl -s https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/socks5.txt | head
  66. ```
  67. The same lists live in a repository of their own, **[maximilianfeix/free-proxy-list](https://github.com/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.
  68. <a href="https://proxy-scraper.de/"><picture>
  69. <source media="(prefers-color-scheme: dark)" srcset="https://proxy-scraper.de/chart-dark.svg">
  70. <source media="(prefers-color-scheme: light)" srcset="https://proxy-scraper.de/chart-light.svg">
  71. <img src="https://proxy-scraper.de/chart-dark.svg" alt="Working proxies over the last days, stacked by protocol – redrawn with every run" width="100%">
  72. </picture></a>
  73. **→ [Browse it on the website](https://proxy-scraper.de/)** – search, filter by type, country, HTTPS, provider and latency, see how long each proxy has been on the list and in how many of the week's runs, copy or download exactly the proxies you need.
  74. Every protocol and country also has its own page with a plain download, e.g. [SOCKS5](https://proxy-scraper.de/socks5/) or [Germany](https://proxy-scraper.de/country/de/) (`country/de/proxies.txt`).
  75. <div align="center"><a href="https://proxy-scraper.de/"><img src="docs/website.png" alt="The live list website" width="860"></a></div>
  76. <a href="https://proxy-scraper.de/"><picture>
  77. <source media="(prefers-color-scheme: dark)" srcset="https://proxy-scraper.de/countries-dark.svg">
  78. <source media="(prefers-color-scheme: light)" srcset="https://proxy-scraper.de/countries-light.svg">
  79. <img src="https://proxy-scraper.de/countries-dark.svg" alt="Countries with the most working proxies right now" width="100%">
  80. </picture></a>
  81. **Where they come from:** [which free proxy lists actually work](https://proxy-scraper.de/sources/) ranks every source of the hourly runs – how many proxies each one lists, how many passed every check and the share. The same as data: [sources.json](https://proxy-scraper.de/sources.json).
  82. **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](../../releases/tag/snapshots-2026) – `proxies-2026-09-27.json.gz` and so on, for anyone who wants to look at free proxies over weeks and months.
  83. Every file is also on the website, which isn't rate limited like raw.githubusercontent and sends CORS headers, so it works straight from the browser: `https://proxy-scraper.de/socks5.txt`. [jsDelivr](https://cdn.jsdelivr.net/gh/maximilianfeix/proxy-scraper@proxy-list/) works too, but can lag behind by a few hours.
  84. Or let the tool start from it: `proxy-scraper --recheck live` downloads the list and checks it again from **your** network – well under a minute instead of a full scan. How many still work from your network differs a lot from the list's own count, which is the point of checking again. Add `--serve` and the result is a rotating proxy.
  85. <a id="the-tool"></a>
  86. ## The tool: check proxies from your own network
  87. The list is checked from GitHub's servers. Whether a proxy works from where your code runs is a different question, and proxy-scraper, the tool that builds the list, answers it: it collects public HTTP, SOCKS4 and SOCKS5 proxies from hundreds of lists, runs up to four checks on each one and keeps the outcome of each check for the proxies it lists (for the rest it counts how each check ended).
  88. https://github.com/user-attachments/assets/b99c1d8f-5bce-4a52-a8a9-b9c2c726301b
  89. <sub>21 seconds · real interface, example numbers, documentation IPs · <a href="docs/video/proxy-scraper.mp4">mp4</a></sub>
  90. ```bash
  91. uvx proxy-scraper-cli --pick 3 --verify # up to 3 proxies from the hourly list that pass right now, from your network
  92. uvx proxy-scraper-cli --diagnose socks5://HOST:PORT # one proxy, check by check: what it did and what it didn't
  93. ```
  94. <div align="center">
  95. <img src="docs/demo/checks.gif" alt="Terminal recording: proxy-scraper --pick 2 --verify --https-only prints two proxies and says on stderr why the other four were left out; proxy-scraper --diagnose shows each check of one proxy with its result" width="880">
  96. </div>
  97. <sub>A real terminal recording, made against six simulated proxies on localhost ([reproduce it](docs/demo/)). It shows how results are reported. It measures nothing about public proxies.</sub>
  98. The package is `proxy-scraper-cli` on PyPI (the plain name is taken). Once [installed](#install), the command is `proxy-scraper`. `--verify` and `--diagnose` need version 1.30 or newer.
  99. **Three ways to get proxies, and what "checked" means for each:**
  100. | Command | Where the proxies come from | Checked | Takes |
  101. |---|---|---|---|
  102. | `proxy-scraper --pick 5` | the [published list](#live-list) | from GitHub's servers when the list was built, about every hour | under a second |
  103. | `proxy-scraper --pick 5 --verify` | the published list | **now, from your network** | seconds; the checks stop after 90 s, plus a few seconds to load the list |
  104. | `proxy-scraper -y` | every list the tool knows | now, from your network | minutes (a few in the hourly runs) |
  105. **What you get**
  106. - **Every check has an outcome you can read.** `passed`, `failed`, `unavailable` or `skipped`, with a reason code, the target and the time, in the terminal, in JSON and from Python. A check target that is down doesn't turn the proxies checked against it into failures. → [Check states](docs/check-states.md)
  107. - **Fresh when it matters.** `--pick --verify` checks a few proxies from your own network, usually in seconds. `--recheck` does the same for [a list of your own](#examples), and `--diagnose` tells you why one proxy doesn't work.
  108. - **More than a list.** A [rotating local proxy server](#proxy-server), a [Python API](#from-python), an [MCP server](#mcp) for AI agents, Docker, and exports for curl, proxychains, Clash and sing-box.
  109. <a id="install"></a>
  110. ## Install
  111. Python 3.9 to 3.14.
  112. **With [pipx](https://pipx.pypa.io/)** (recommended – gives you a `proxy-scraper` command in its own environment):
  113. ```bash
  114. pipx install proxy-scraper-cli
  115. proxy-scraper
  116. ```
  117. **With [Homebrew](https://brew.sh)** on macOS and Linux:
  118. ```bash
  119. brew install maximilianfeix/tap/proxy-scraper
  120. ```
  121. The formula follows each release within about a day.
  122. Docker, pip, a faster event loop, the latest main, tab completion and where state and results are stored: [every other way to install](docs/install.md).
  123. Started without arguments, a wizard asks what you are looking for – a preset (find everything, browsing, maximum anonymity, fast, a few right now, recheck, proxy server right away, …) or step by step: [the wizard and its presets](docs/options.md#wizard-presets).
  124. Keys: <kbd>↑</kbd><kbd>↓</kbd> select · <kbd>Space</kbd> toggle · <kbd>1</kbd>–<kbd>9</kbd> jump · <kbd>Enter</kbd> next · <kbd>Esc</kbd> back · <kbd>q</kbd> quit. In scripts and cron jobs the wizard never shows up – pass options or `-y`.
  125. <a id="check-states"></a>
  126. ## Check states
  127. Every check of a proxy ends in one of four states. They are in `proxies.json`, in the CSV, in `--pick --json`, in `--diagnose`, in the Python API (`result.checks`) and in the MCP results.
  128. | State | Meaning |
  129. |---|---|
  130. | `passed` | The check ran and the proxy did what was asked. |
  131. | `failed` | The check ran, its target was fine, and the proxy did not do what was asked. |
  132. | `unavailable` | The check could not run, or says nothing about the proxy: its target didn't answer directly either, there was no reference to compare with, or this machine ran out of sockets. |
  133. | `skipped` | Left out on purpose: `--fast`, a filter had already ruled the proxy out, or an earlier check failed. |
  134. Two rules follow from that:
  135. - **A check that didn't run is never `passed`.** Before 1.30, a run without a reachable second target kept every proxy as if it had been confirmed, and a missing reference page looked like "content unchanged".
  136. - **A check target that is down doesn't fail the proxies checked against it.** When a second request, a content request that returned a different page, or an HTTPS test fails, the tool asks the target directly: at most once every 3 seconds however many proxies fail in between, and a "down" answer is reused for 10 seconds. If the target doesn't answer, the proxy's check is `unavailable`, not `failed`. For the first request a scan does it differently: it watches the target, switches to another one and checks the affected proxies again. `--diagnose` and `--pick --verify` have no such watcher and ask directly, as for the later checks. Two things are never asked about, because the target did answer: a second site that saw a different exit IP, and a proxy that could not be connected to in the first place.
  137. The checks, what each `passed` does and doesn't mean, the fields and every reason code: [docs/check-states.md](docs/check-states.md).
  138. <a id="mcp"></a>
  139. ## For AI agents (MCP)
  140. <!-- mcp-name: io.github.maximilianfeix/proxy-scraper -->
  141. `proxy-scraper-mcp` is an [MCP](https://modelcontextprotocol.io) server: Claude Code, Claude Desktop, Cursor, VS Code, Codex and any other MCP client can ask for working proxies and load pages through them.
  142. [![proxy-scraper MCP server on Glama](https://glama.ai/mcp/servers/maximilianfeix/proxy-scraper/badges/score.svg)](https://glama.ai/mcp/servers/maximilianfeix/proxy-scraper)
  143. | Tool | What it does |
  144. |---|---|
  145. | `get_proxies` | proxies from the hourly list, as checked in its last run – filter by protocol, country, HTTPS, elite, no datacenter, not blocklisted, stable, uptime, latency, gets through to Google/Reddit/Amazon |
  146. | `check_proxies` | checks proxies from your own network, so they work from where your code runs (30–90 s, reports progress) |
  147. | `fetch_url` | loads a page through a proxy from the checked list, switches proxies by itself when one fails, returns readable text – HTTPS only through proxies that passed the TLS test |
  148. 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"*.
  149. Needs [uv](https://docs.astral.sh/uv/) – it fetches a suitable Python by itself if yours is older than 3.10. **Claude Code:**
  150. ```bash
  151. claude mcp add proxy-scraper -- uvx --python ">=3.10" --from "proxy-scraper-cli[mcp]" proxy-scraper-mcp
  152. ```
  153. **Claude Desktop, Cursor and most other clients** – add this to the MCP config (Claude Desktop: Settings → Developer → Edit Config, Cursor: `~/.cursor/mcp.json`):
  154. ```json
  155. {
  156. "mcpServers": {
  157. "proxy-scraper": {
  158. "command": "uvx",
  159. "args": ["--python", ">=3.10", "--from", "proxy-scraper-cli[mcp]", "proxy-scraper-mcp"]
  160. }
  161. }
  162. }
  163. ```
  164. **VS Code, Codex, Docker, or without uv:** [setup for every other client](docs/mcp.md). It's also in the [official MCP registry](https://registry.modelcontextprotocol.io) as `io.github.maximilianfeix/proxy-scraper`, so clients that browse the registry can install it from there.
  165. 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.
  166. <a id="examples"></a>
  167. ## Examples
  168. ```bash
  169. # 50 proxies that can do HTTPS – then stop
  170. proxy-scraper --want 50 --https-only
  171. # only Germany, Austria and Switzerland, the 20,000 most promising candidates
  172. proxy-scraper --country DE,AT,CH -l 20000
  173. # fast elite SOCKS5 proxies
  174. proxy-scraper --types socks5 --anonymity elite --max-latency 1500
  175. # 20 proxies that really reach Google AND Discord
  176. proxy-scraper --target google.com --target discord.com --want 20
  177. # only recheck the last hits (plus history) – takes seconds
  178. proxy-scraper --recheck
  179. # wizard with defaults – it keeps what you already passed
  180. proxy-scraper -i --country DE
  181. # which sources deliver the most?
  182. proxy-scraper --list-sources
  183. ```
  184. Running from a clone? Replace `proxy-scraper` with `python3 proxy_scraper.py`.
  185. <a id="from-python"></a>
  186. ### From Python
  187. ```python
  188. from proxyscraper import check_proxies, find_proxies
  189. if __name__ == "__main__": # needed on macOS/Windows, the parser uses a process pool
  190. for p in find_proxies(want=20, https=True, countries=["DE", "NL"], no_datacenter=True):
  191. print(p.url, p.latency, p.country, p.org)
  192. alive = check_proxies(["socks5://1.2.3.4:1080", "5.6.7.8:3128"]) # your own list
  193. ```
  194. 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`).
  195. Don't need a fresh scan? `live_proxies` takes the [live list](#live-list) instead – no checks, one download, done in about a second:
  196. ```python
  197. import itertools, requests
  198. from proxyscraper import live_proxies
  199. proxies = live_proxies(types=["socks5"], https=True, min_uptime=90) # the reliable ones this week
  200. pool = itertools.cycle(p.url for p in proxies)
  201. r = requests.get("https://api.ipify.org", proxies={"https": next(pool)}, timeout=15) # pip install "requests[socks]"
  202. ```
  203. It filters by `types`, `countries`, `https`, `anonymity`, `max_latency`, `no_datacenter` and `no_blocklisted` like `find_proxies`, plus `min_uptime`, `min_speed` (KiB/s), `works_on` (`["google"]`, `"reddit"`, `"amazon"`, `"instagram"`, `"tiktok"`, `"discord"`) and `limit`. Every result also has `uptime_24h`, `uptime_7d`, `first_seen`, `up_for_hours`, `sites` and `speed_kbps`.
  204. Or let the library do the retrying: `ProxyRotator` loads a URL through the list and moves on to the next proxy when one fails, and `proxy_url()` gives requests, httpx, Playwright or Scrapy one local address that rotates behind the scenes – [Python API: rotating through the list](docs/python.md).
  205. <a id="proxy-server"></a>
  206. ## Rotating proxy server
  207. A list is nice – but usually you just want to enter **one** proxy address and have something behind it that keeps trying:
  208. ```bash
  209. proxy-scraper --recheck --serve # recheck the last hits, then go – takes seconds
  210. ```
  211. ```bash
  212. curl -x http://127.0.0.1:8899 https://api.ipify.org # a different IP every time
  213. curl -x socks5h://127.0.0.1:8899 https://api.ipify.org # SOCKS5 on the same port
  214. curl -x http://country-de:x@127.0.0.1:8899 https://api.ipify.org # only German exits
  215. curl -x http://session-cart42:x@127.0.0.1:8899 https://shop.example # same proxy for this session
  216. curl http://127.0.0.1:8899/__proxy-scraper/status # pool and counters as JSON
  217. curl http://127.0.0.1:8899/__proxy-scraper/metrics # the same for Prometheus/Grafana
  218. ```
  219. 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`.
  220. 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:
  221. ```bash
  222. export PROXY_SCRAPER_SERVE_PASSWORD=$(openssl rand -hex 16) # the env var keeps it out of `ps`
  223. proxy-scraper --recheck --serve --serve-host 0.0.0.0
  224. curl -x "http://country-de:$PROXY_SCRAPER_SERVE_PASSWORD@your-server:8899" https://api.ipify.org
  225. ```
  226. Without a password the server refuses to start on any address but `127.0.0.1`: that would be an open proxy for **anyone who reaches the port** (Docker publishes ports past host firewalls like ufw). If a firewall or `-p 127.0.0.1:…` already keeps others out, say so with `--serve-open`. The ready-made [`compose.yaml`](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`.
  227. Rotation strategies, sticky sessions, failover, background refill and the live dashboard: [docs/proxy-server.md](docs/proxy-server.md).
  228. <a id="pool-api"></a>
  229. ### Proxy pool API
  230. 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:
  231. ```bash
  232. curl http://127.0.0.1:8899/get # one proxy as JSON, chosen like a connection would be
  233. curl "http://127.0.0.1:8899/get?country=DE&https=1&format=txt" # → http://203.0.113.7:8080
  234. curl "http://127.0.0.1:8899/all?protocol=socks5&limit=20" # the 20 best SOCKS5 proxies
  235. 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
  236. ```
  237. All endpoints, filters and what's compatible with jhao104/proxy_pool: [Proxy pool API](docs/proxy-server.md#pool-api).
  238. <a id="discord-bot"></a>
  239. ## Discord and Telegram bot
  240. The live list can also come to you: [`bot/`](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](bot/README.md).
  241. <a id="docs"></a>
  242. ## Documentation
  243. Everything that used to be further down this README now has its own page – [all docs](docs/README.md):
  244. <a id="features"></a>
  245. ### Features
  246. What the tool does, check by check and feature by feature: [How it works → Features](docs/how-it-works.md#features).
  247. <a id="why-not-just-download-a-list"></a>
  248. ### Why not just download a list?
  249. A list tells you what worked for its author when it was built. What the tool adds: [How it works → Why not just download a list?](docs/how-it-works.md#why-not-just-download-a-list) · [how it compares](docs/comparison.md).
  250. <a id="how-it-works"></a>
  251. ### How it works
  252. Sources, collecting, prioritizing, the checks, countries and providers, blocklists, learning: [docs/how-it-works.md](docs/how-it-works.md). Your own lists with `--source`: [recipes](docs/recipes.md#your-own-lists).
  253. <a id="output"></a>
  254. ### Output
  255. Every run gets its own folder; `results/latest.txt` always names the newest one – the layout is in [docs/options.md](docs/options.md#output).
  256. <a id="recipes"></a>
  257. ### Recipes
  258. requests, httpx, aiohttp, Scrapy, Selenium, proxychains, Clash / Mihomo, sing-box, PAC, Proxifier, Burp Suite / ZAP / mitmproxy, pipes, a GitHub workflow, Windows: [docs/recipes.md](docs/recipes.md).
  259. <a id="options"></a>
  260. ### Options
  261. Every option in one table: [docs/options.md](docs/options.md). Everything else: `proxy-scraper --help`
  262. <a id="github-actions"></a>
  263. ### GitHub Actions
  264. The workflows that test, lint, build the hourly list and release: [docs/how-it-works.md](docs/how-it-works.md#github-actions). To use proxies in your own workflow: [the GitHub Action](docs/github-action.md).
  265. <a id="faq"></a>
  266. ### FAQ
  267. [Who runs free proxies – and should you use them?](docs/faq.md#who-runs-free-proxies) · almost nothing gets through · Windows · fewer proxies than other lists · logins · how fresh the list is · is it safe: [docs/faq.md](docs/faq.md).
  268. <a id="who-runs-free-proxies"></a>
  269. <a id="roadmap"></a>
  270. ### Roadmap
  271. What's next is in the [open issues](../../issues) – ideas and wishes are welcome as an [issue](../../issues/new/choose). During Hacktoberfest there are [beginner-friendly issues](../../issues?q=is%3Aopen+label%3Ahacktoberfest) with pointers on where to start. What shipped in each version: [docs/roadmap.md](docs/roadmap.md).
  272. <a id="contributing"></a>
  273. ## Contributing
  274. Bug reports, new sources and pull requests are very welcome – see [CONTRIBUTING.md](CONTRIBUTING.md), and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for how the pieces fit together. The short version:
  275. ```bash
  276. pip install -e ".[dev]"
  277. python3 -m pytest # runs offline – fake proxies on localhost
  278. ruff check .
  279. python3 docs/make_demo.py # regenerate the images in this README
  280. ```
  281. The project structure, file by file, is in [How it works](docs/how-it-works.md#project-structure).
  282. <a id="community"></a>
  283. ## Community
  284. Questions, ideas and things you built with it go to [Discussions](https://github.com/maximilianfeix/proxy-scraper/discussions) – bugs to the [issues](../../issues). If this saves you time, a ⭐ helps others find it.
  285. Thanks to everyone who helped build it – new sources, countries, Python 3.14, examples and more:
  286. <a href="https://github.com/maximilianfeix/proxy-scraper/graphs/contributors">
  287. <img src="https://contrib.rocks/image?repo=maximilianfeix/proxy-scraper" alt="Contributors to proxy-scraper">
  288. </a>
  289. Want to join? [Beginner-friendly issues](../../issues?q=is%3Aopen+label%3A%22good+first+issue%22) say where to start.
  290. From the same author: [dejabuilt](https://github.com/maximilianfeix/dejabuilt), an agent skill that checks GitHub before you build – it tells you whether a project idea already exists, with the numbers.
  291. <a href="https://star-history.com/#maximilianfeix/proxy-scraper&Date">
  292. <picture>
  293. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=maximilianfeix/proxy-scraper&type=Date&theme=dark">
  294. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=maximilianfeix/proxy-scraper&type=Date">
  295. <img alt="Star history of proxy-scraper" src="https://api.star-history.com/svg?repos=maximilianfeix/proxy-scraper&type=Date" width="600">
  296. </picture>
  297. </a>
  298. <a id="acknowledgements"></a>
  299. ## Acknowledgements
  300. proxy-scraper stands on the work of the people who publish free proxy lists. Thanks to everyone listed in [`sources.json`](proxyscraper/sources.json), and especially to
  301. - [monosans/proxy-scraper-checker](https://github.com/monosans/proxy-scraper-checker) and [gfpcom/free-proxy-list](https://github.com/gfpcom/free-proxy-list), whose curated source collections are read as meta sources
  302. - [Textualize/rich](https://github.com/Textualize/rich), which draws the whole terminal UI
  303. - [IP Geolocation by DB-IP](https://db-ip.com) – the free country database (CC BY 4.0) used for offline country lookups
  304. - [httpbin](https://httpbin.org), [checkip.amazonaws.com](https://checkip.amazonaws.com), [ifconfig.me](https://ifconfig.me), [ipinfo.io](https://ipinfo.io), [wtfismyip.com](https://wtfismyip.com), [ident.me](https://ident.me) and [ip-api.com](https://ip-api.com), used as check targets and for country lookups, and [speed.cloudflare.com](https://speed.cloudflare.com) for the download speed
  305. ## Legal and acceptable use
  306. proxy-scraper collects proxies that are already listed publicly and checks whether they work. It doesn't scan for open proxies or get into anything: every address comes from one of the [public sources](proxyscraper/sources.json).
  307. - The proxies are run by third parties, often without the owner knowing. Use them only for legal purposes, and never for logins, payments or personal data. You are responsible for how you use them: respect the terms of the sites you visit and the laws where you live.
  308. - **Your address on the list?** Open a [removal request](https://github.com/maximilianfeix/proxy-scraper/issues/new?template=remove_address.yml) or email the address in the [Impressum](https://proxy-scraper.de/legal.html#impressum). It goes into [`removed.txt`](removed.txt) and is gone from every list, the website and the mirror with the next hourly run.
  309. - Impressum and privacy policy: [proxy-scraper.de/legal.html](https://proxy-scraper.de/legal.html). The website sets no cookies, has no tracking and loads its fonts and scripts from itself.
  310. <div align="center">
  311. ---
  312. <sub>Made in Germany by <a href="https://github.com/maximilianfeix">@maximilianfeix</a> · <a href="LICENSE">MIT License</a> · <a href="CHANGELOG.md">Changelog</a> · <a href="SECURITY.md">Security</a> · <a href="CONTRIBUTING.md">Contributing</a></sub>
  313. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.