wechat-download-api: RSS, MCP and Bulk Export for WeChat Official Accounts

The gap between WeChat's reading experience and everything else

WeChat official accounts publish inside a closed client. There is no public per-account feed, no stable article index you can poll, and no export button. If you want a subscription in FreshRSS, or you want an AI agent to summarise the last ten posts from an account, you are doing it by hand. This project attacks that gap from two directions at once: a standard RSS 2.0 feed per account, and an HTTP API that returns article bodies, author, image lists and account metadata. The README describes the RSS output as containing full article content and images, not just titles and links, which matters because a headline-only feed still forces you back into the WeChat client.

The audience is narrower than the description suggests. The stated prerequisite is that you own a WeChat official account (subscription or service account), because the service authenticates by having the account administrator scan a QR code through the WeChat public platform backend. Once logged in, the API can read public articles from any account, not only your own. So the tool is for people who happen to hold an admin role on some account, and who want to read or archive other accounts. That is a real but specific population: media monitoring teams, researchers, developers building on WeChat content, and individuals who registered an account for exactly this purpose.

Login credentials, not scraping, are the load-bearing mechanism

The architecture is a FastAPI service that holds a WeChat public platform session server-side. You scan a QR code at /login.html, the credential is written into .env, and it is described as valid for roughly four days. Every subsequent API call rides on that session. This is why the HTTP endpoints listed in the README need no token from the caller: the login state is internal, and the README says so explicitly, noting that MCP_TOKEN and the Authorization header apply only to the MCP endpoint and are unrelated to those HTTP interfaces.

On top of that session sits an anti-throttling layer the README summarises as Chrome TLS fingerprint simulation, SOCKS5 proxy pool rotation, and three-tier automatic rate limiting. The design assumption is that WeChat will notice repeated requests from one fingerprint and one IP, so the service varies both. What the documentation does not give is any figure for how many requests per hour the three tiers permit, or how large a proxy pool needs to be. That is a gap you will have to measure yourself, and it is the single most likely place for a deployment to degrade quietly.

The export path is deliberately separated from the fetch path. The README states that bulk account export reads the local database only and triggers no WeChat requests, which is why the format table can promise 3000 articles per batch for Markdown, HTML, Excel and JSON. Word, PDF and EPUB are capped lower (500, 200 and 500 respectively) because those formats fetch WeChat images and embed them so the file works offline.

Running it: Docker, a one-line script, or systemd

The README gives two deployment routes. The Docker route is the shorter one:

git clone https://github.com/tmwgsicp/wechat-download-api.git cd wechat-download-api cp env.example .env docker-compose up -d

The README instructs you to edit .env and set SITE_URL to the actual access address before starting. There is also a direct docker run form that mounts ./data into /app/data and ./env into /app/.env, publishing port 5000. Images are published for linux/amd64 and linux/arm64, so Apple Silicon and ARM servers are covered.

The script route is bash start.sh on Linux or macOS, start.bat on Windows, and the README says it handles environment checks, virtual environment creation, dependency installation and service start. Run it with sudo on Linux and it registers a systemd unit named wechat-download-api and enables it at boot. Management afterwards is bash status.sh, bash stop.sh, or sudo systemctl restart wechat-download-api. The README also supplies an Nginx reverse proxy block forwarding to 127.0.0.1:5000 with the usual Host and X-Forwarded-For headers.

For AI clients, MCP mounts at /mcp using streamable-http. Two environment variables matter and the README is blunt that both are required: ENABLE_MCP=1 and MCP_TOKEN set to a long random string. If either is missing, MCP does not start. When deployed behind a public domain you also set MCP_RESOURCE_URL so the DNS-rebinding allowlist matches. The six exposed tools are search_accounts, subscribe_account, unsubscribe_account, list_subscriptions, get_recent_articles and read_article. Client setup is a single command for Claude Code (claude mcp add --transport http wechatrss ... --header "Authorization: Bearer <MCP_TOKEN>") or a JSON block with url and headers for Cursor and Cline. Requests without the correct token return 401.

The four-day credential is the design's weak point

Everything above depends on a session that expires. The README puts the validity at about four days and states that you re-scan when it lapses. There is a webhook notification feature that warns 24 hours and 6 hours before expiry and again after it has expired, with support for a WeCom bot. That softens the failure but does not remove it: an unattended server will stop fetching, and the RSS feed will simply go quiet rather than error loudly in your reader.

There is a second, harder boundary. Because the service authenticates through the WeChat public platform backend, you need an account you administer. If your organisation has no such account, or the admin will not scan a QR code on a third-party service, this project is the wrong tool regardless of how well it works technically. The README does not describe any credential-free mode.

A third limitation is legal and operational rather than technical. The project is licensed AGPL-3.0, which is a strong copyleft licence. If you modify it and expose it over a network, the AGPL's network clause is generally understood to require offering the modified source to users. I am not a lawyer and this is not legal advice; if you plan to run a modified version as a service for others, read the licence text or get counsel.

Finally, the README is thin on the anti-throttling specifics. TLS fingerprint simulation and proxy rotation are named, but no concurrency guidance, no retry policy and no failure thresholds are documented. The README also does not state what happens to an in-flight bulk export if the session expires mid-run.

How this differs from RSSHub and from generic article scrapers

RSSHub is the obvious comparison for the feed half of this project, and the difference is in how each obtains data. RSSHub's WeChat routes have historically relied on third-party intermediaries and public endpoints that break when those services change or disappear; it is a route catalogue, and each route carries its own fragility. This project instead authenticates as a logged-in WeChat public platform user and calls the platform's own backend interfaces, which is why it needs an account and a QR scan at all. The trade is explicit: you accept a four-day credential and an account requirement in exchange for not depending on someone else's intermediary.

Against a general-purpose scraper such as a headless browser pointed at mp.weixin.qq.com, the difference is where the work happens. A scraper re-fetches each article page every time and fights the same anti-bot measures on every request. Here, articles are fetched once into a local database, and the export formats read from that database. The README makes this distinction a selling point for bulk export, and it is a genuine architectural difference: the expensive, risky operation happens once, and the cheap operation can be repeated. The cost is that whatever was never fetched is not in the export, and the README notes that exports include only articles whose bodies have already been captured.

Maintenance cost and what the release cadence implies

Three releases between June and July 2026 (v1.5.1, v1.6.0, v1.7.0), with the last push on 2026-07-27, indicate an actively maintained project rather than an abandoned one. That cadence also tells you something about the maintenance burden you inherit: a service that wraps a platform's private backend interfaces has to be updated when that backend changes. Expect to pull new images periodically, and expect occasional breakage between releases. Running docker-compose with a pinned tag rather than latest gives you control over when that happens.

Day-to-day cost is mostly the QR re-scan every four days, plus proxy pool upkeep if you enable rotation and hit volume. The webhook feature exists precisely to reduce the human cost of the former. Storage grows with the article database, but the README gives no size figures, so budget for it yourself.

The AGPL-3.0 licence means self-hosted private use is unconstrained, while redistributing or offering a modified version as a network service carries source-disclosure obligations. There is also a hosted SaaS version at wechatrss.waytomaster.com mentioned in the README, which is worth knowing about as an escape hatch if the self-hosted path proves too maintenance-heavy for your situation.

Editorial conclusion

Adopt it if you already administer a WeChat official account, can re-scan a QR code roughly every four days, and want your subscriptions inside FreshRSS or an MCP-capable AI client rather than a browser tab. Do not adopt it if nobody on your team holds an account admin role, or if you need unattended operation for months without human intervention. Before deploying, verify three things: that your .env sets both ENABLE_MCP and MCP_TOKEN (either one missing leaves MCP disabled), that SITE_URL matches the address clients will actually reach, and that your SOCKS5 proxy pool is sized for the fetch volume you plan, since the anti-throttling layer is the part most likely to fail under load.

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. tmwgsicp/wechat-download-api on GitHub