telegram-proxy-collector: a two-hourly pipeline for MTProto proxies that reads the secret

A collector built around one detail of the MTProto secret

This project is described as an anti-censorship edition tool for collecting, analysing and filtering MTProto and SOCKS5 proxies, and the README is written in Russian. Its distinguishing claim is that unlike ordinary parsers it deeply analyses the `Secret` of each MTProto proxy, extracts the domain mask, filters by GeoIP, and discards junk ports.

The domain masks it looks for are the names of popular services: Yandex, VK, Mail.ru, Gosuslugi, Google, Amazon and Cloudflare among them. In Fake-TLS mode, an MTProto client presents itself as if it were connecting to one of those sites, which is what makes the traffic hard to block by signature. So the mask is not decoration, it is the property that makes a proxy useful in a network that blocks the real protocol.

The version 4.1 notes describe the mechanism and a bug in it. The `decode_domain` fix means the Fake-TLS domain is now read from position 34, the `ee` prefix plus 32 hex characters of secret equalling 16 bytes, rather than from position 2. Previously the region was determined incorrectly or at random. That single line tells you a lot about the project: the value of the output depends entirely on parsing one field of one structure, and an off-by-one in that parse silently mislabels every proxy in the list.

There is also a `MANUAL_PROXIES` block in the code for proxies that are always checked regardless of the sources, described as convenient for your own servers and private MTProto instances. That is a useful thing to know about, because it means the published lists are not purely a function of the public sources.

The intended user is someone in a censored network who needs working Telegram proxies, and the tool is explicitly framed around the situation of hard blocking, where masking as legitimate HTTPS or using SOCKS5 can be the difference between working and completely unreachable.

GeoIP filtering before the TCP check, to save time

The order of operations is the interesting engineering decision in this pipeline, and the README explains the rationale.

GeoIP filtering uses the `GeoLite2-Country.mmdb` database, which is updated daily, and proxies from untrusted countries are discarded before the TCP check, which saves time and traffic. Sixty or more trusted countries are in the list.

Doing the cheap filter first is the right order. A TCP check is a network round trip, and the number of candidates is large, so removing the obviously unusable candidates before they reach the network is what makes a full run finish in a sensible time.

The geographic policy is worth stating plainly, because it is a policy rather than a technical fact. The extended geography adds ASIA with JP, KR, SG, HK, IN, TW, PH, MY, ID, VN, TH and MN, plus US, the Middle East and Mexico. The Fake-TLS detector extracts the SNI domain from the secret and uses it to determine a region, one of `ru`, `eu`, `us` or `asia`, which is how the regional lists are built. A proxy whose mask says Yandex lands in the RU list, one masked as Google in the EU list.

The second filter is by port. Forty-five or more ports are discarded automatically for MTProto, including 22, 80, 3306, 5432, 8080, 8443 and 25565, and the README names the categories they represent as SSH, MySQL, Tomcat and Minecraft. The reasoning is obvious once stated: an open SSH or database port that answers is not an MTProto proxy, and a naive checker will happily report it as a live host.

There is a fallback for the GeoIP lookup, from `maxminddb.open_database` to `geoip2.database.Reader`, described as being for compatibility, and the `.env.example` file shows where the database paths come from, with `GEOLITE2_COUNTRY_PATH` and `GEOLITE2_ASN_PATH` as optional variables.

The pipeline, the 48 hour cache and the 30,000 proxy ceiling

The script runs every two hours through GitHub Actions, and the README says it goes through six main stages, the first of which is harvesting, downloading raw proxies from sources. The Actions workflow saves the results into the `verified/` folder and then copies them into the root of the repository, which is why the direct links always point at fresh lists.

The published versions show a very short cycle, with tags such as v2026.10.15-194501-38796080126-1, v2026.10.15-144308-38753529464-1 and v2026.10.15-085641-38708987255-1 on the same day. The naming pattern carries a timestamp and a counter, and the last push to the default branch was on 2026-10-19, so the repository is being updated several times a day rather than released on a schedule.

Three implementation details govern the behaviour a user actually sees.

The first is the TTL seen cache. Proxies are not checked twice within 48 hours, and the cache key includes the `secret`, so different MTProto instances on one IP are not treated as duplicates. That key detail is what stops the cache from collapsing distinct proxies that share a host, which would otherwise silently shrink the usable set.

The second is the volume limit, `--max-check`, which defaults to 30,000 and is described as protection against heavy runs. Combined with 200 workers, the README claims 30,000 proxies are checked in roughly 40 seconds. Treat that as the project's own figure rather than a measured guarantee, since the actual time depends on the network and on how many candidates are discarded before the check.

The third is that a large part of the pipeline is not about proxies at all. `analytics.py` trains a RandomForest for quality and an IsolationForest for anomalies, and computes trends between runs. There is a `ping_history.json` and a `tcp16.json` in the tree, plus a `models/` directory, which is where the trained artefacts and the measurement history live. The `tests/` directory, `config.yml`, `domains.txt` and `whitelist_sni.txt` complete the picture, the last of them being the list of SNI names treated as acceptable masks.

The published lists and the mobile page

The deliverable of the project is a set of plain text files, and the README links them directly for pasting into Telegram or into other programs.

`proxy_ru.txt` is the RU segment, masked as Yandex, VK, Mail.ru, Gosuslugi, Sber, Mos.ru and others, and it is described as aimed at the best stability in Russia and Iran. `proxy_eu.txt` is the EU and global list, masked as Google, Amazon and Cloudflare, with a note that it has high speed and stability especially outside Russia. `proxy_us.txt` covers the United States and Canada. `proxy_asia.txt` covers JP, KR, SG, HK, IN, TW, PH, MY, ID, VN, TH and MN. `proxy_all_mtproto.txt` is the full mix of every checked MTProto server across those regions, `proxy_all.txt` is RU and EU together, and `socks5.txt` holds SOCKS5 proxies, which have no masking but, as the table says, are often harder to block.

For use on a phone, the repository publishes a GitHub Pages site whose `index.html` sits at the root, with tabs for MTProto RU, EU, US and ASIA and for SOCKS5. Pressing a button hands the proxy to Telegram, which offers to connect. There is also a `mobile.html` built for small screens with a simplified interface.

The dependency list in `requirements.txt` shows the shape of the implementation. Requests and PyYAML for the core, Telethon and `python-socks[asyncio]` for the Telegram side, `maxminddb` and `geoip2` for GeoIP, NumPy, scikit-learn and pandas for the data and machine learning work, and the OpenAI client. The `.env.example` shows the credentials the tool expects, with `TELEGRAM_API_ID` and `TELEGRAM_API_HASH` for the Telegram API, optional `OPENAI_API_KEY` and `GROK_API_KEY` for the AI features, and the two GeoLite2 paths.

A language model writes part of the README

The version 4.1 notes include a line that deserves more attention than its position in the list: AI analytics, where the Groq model `openai/gpt-oss-120b` automatically updates a block in the README.

So part of this project's documentation is generated by a language model. That is not automatically a problem, but it changes how you should read the document. The generated block is a summary of what the run did, written by a model rather than by the script, and it is not a specification of behaviour. Where the generated text and the code disagree, the code is the truth, and where the generated text makes a claim about results, it is a claim without a measurement behind it.

The same caution applies to the file lists and the feature notes. The lists of countries, the port counts and the timing figures are the project's own assertions, and a reader who is going to rely on them should check them against the `config.yml` and the code.

The `ai_analytics.py` file in the tree is the AI part of the pipeline, and the `openai>=3.29.0` dependency with the `GROK_API_KEY` variable in the environment example shows how it reaches the model. The `data/`, `reports/` and `models/` directories are where the run outputs, the reports and the trained models live, and the `ping_history.json` file carries the measurement history that the trend analysis works from.

The licence is the other thing to look at before you build on this. The project metadata records the licence as unknown, and there is no licence file among the top-level entries, so the terms for redistributing the collected lists, the code, or the trained models are not stated. That is worth resolving with the author rather than assuming, and it is a description of what the repository contains rather than legal advice.

What the tool is, and what it is not

It is worth being clear about what this project does and does not give you, because the output looks authoritative and is not.

It gives you a filtered, refreshed, region-sorted list of proxies that answered a TCP check, drawn from public sources, with their masks classified and their geography screened. It does not give you proxies that anyone vouches for. A TCP check establishes that something was listening and reachable at the time of the check, and nothing more. The proxy can be monitored, can log traffic, can be a honeypot, and will in most cases be the IP of someone who did not choose to run a proxy for your benefit.

That makes the security question the central one, and it is a question the tool does not answer. Every proxy in these lists sits between you and Telegram, and the traffic you send through it, including the session material that protects your account, passes through infrastructure you do not control.

The legal question is the second one, and it is jurisdiction-specific. The project frames itself explicitly as an anti-censorship tool for hard blocking situations, which is a legitimate use in many countries and a prohibited one in others, and the repository's own tooling is a crawler that pulls from public lists and publishes the result. Whether running it, or using the lists, is lawful where you are is not something the code can answer.

The alternative approach is a proxy you host yourself, or a subscription service with a commercial relationship and an abuse policy. The difference in approach is that a self-hosted proxy is yours to monitor and yours to log, at the cost of the bandwidth and the exposure of running an open service, while these lists give you a working proxy in a few seconds and none of the visibility.

The middle position, which is what the `MANUAL_PROXIES` block already gestures at, is to use the collector to find candidates and then run your own checks on them, in your own environment, with your own threat model, rather than trusting a published list that someone else regenerated two hours ago.

Editorial conclusion

Adopt this collector if you specifically need MTProto proxies that masquerade as ordinary HTTPS, because the domain mask extracted from the secret and the GeoIP filter are what separate a working proxy from a dead one, and the two-hourly refresh means the lists do not rot. Do not adopt it as a general proxy source, since the proxies are unvetted third party infrastructure and the tool publishes them in the clear, and do not treat its README as a specification, because the project states that a language model rewrites part of it. Verify three things first: that the GeoLite2 database path in your environment points at a file you trust, since every proxy in the output was selected by that file, that you understand what your traffic traverses when you use a proxy you did not host, and that using it is lawful where you are, because the tool's own framing is built around avoiding blocks.

Frequently asked questions

Official sources

1. Issues
2. kort0881/telegram-proxy-collector on GitHub
3. Project website
4. README
5. Releases