WECHAT-MP-MCP

# wechat-mp-mcp A Model Context Protocol (MCP) server for crawling WeChat Official Account articles via the `mp.weixin.qq.com` subscription-account search interface. Works with any MCP-compatible client (Claude Code, Claude Desktop, Cline, Continue, Cursor, etc.). ## What it does Given a WeChat Official Account name, this server can: - search for the account and resolve its internal `fakeid` - pull the article list (full history on first crawl, incremental afterwards) - fetch a single article and convert its body to Markdown - store everything in a local SQLite database (deduped by URL) Built-in safeguards: daily quota cap (default 150), jittered delays, randomized page sizes, work-hours gate. ## Requirements - Python 3.10+ - A personal **WeChat subscription account (订阅号)**. You log in once via QR code at <https://mp.weixin.qq.com/>, then this server reuses your login session to call the public-account search interface. > **Why a subscription account?** The search interface is normally used by > account operators when writing articles ("insert link → from another > account"). This server reuses that flow. The account is **only used as > a login key** — you don't need to publish anything from it. Register one > at <https://mp.weixin.qq.com/> (free, ~15 minutes, ID verification > required). > **Personal WeChat is NOT touched.** Your chat history, payments, and > friends are completely unrelated to this — only your subscription-account > backend session is used. ## Install ```bash git clone https://github.com/fdslk/WECHAT-MP-MCP.git wechat-mp-mcp cd wechat-mp-mcp ./install.sh ``` `install.sh` is idempotent. It will: 1. check Python 3.10+ 2. create `.venv` and install all deps (including Playwright Chromium ~92 MB) 3. **prompt** you to scan a QR code to log in (Chromium opens automatically) 4. **prompt** to register with Claude Code if the `claude` CLI is on your PATH Rerun it anytime — it skips steps that are already done. ### Manual install (if you don't want install.sh) ```bash python3 -m venv .venv .venv/bin/pip install -e '.[login-auto]' # drop [login-auto] to skip Playwright .venv/bin/playwright install chromium # ~92 MB one-time .venv/bin/wechat-mp-mcp-login-auto # opens browser for QR scan claude mcp add wechat-mp --scope user $(pwd)/.venv/bin/wechat-mp-mcp ``` ## Login `install.sh` runs login for you. If you skipped it, or your session expired (typical lifetime 1-2h), re-run: ```bash .venv/bin/wechat-mp-mcp-login-auto # automated: Chromium + QR scan # or .venv/bin/wechat-mp-mcp-login # manual: paste URL + Cookie from DevTools ``` Credentials are saved to `~/.config/wechat-mp-mcp/auth.json` (chmod 600). ## Wire into other MCP clients For **Claude Code**, `install.sh` does this. For everything else (Claude Desktop, Cline, Continue, Cursor, etc.), add a stdio entry: ```json { "mcpServers": { "wechat-mp": { "command": "/absolute/path/to/wechat-mp-mcp/.venv/bin/wechat-mp-mcp" } } } ``` ## Tools exposed | Tool | Cost | Purpose | |---|---|---| | `search_account(query, limit=5)` | 1 API call | Resolve account name → `fakeid` | | `list_articles_page(fakeid, begin=0, count=5)` | 1 API call | Pull one page of metadata. Use for full-history crawl — call repeatedly with growing `begin` until `returned == 0` | | `crawl_incremental(fakeid, max_pages=10, delay_seconds=1.5, override_work_hours=False)` | 1-N API calls | Pull only articles newer than what is stored. Stops on first overlap with local DB | | `fetch_article(url, save=True)` | 0 (public page) | Fetch + parse one article body to Markdown | | `quota_status()` | 0 (local) | Report today's API call usage vs daily cap | | `list_stored_articles(fakeid, limit=20, offset=0, with_body=False)` | 0 (local) | Query the local store | `fetch_article` doesn't consume the daily quota because article pages (`mp.weixin.qq.com/s/...`) are public — only the search backend has a cap. ## Typical workflow (natural language) After wiring into Claude Code, you can just say: ``` "Search the WeChat account 'Foo Bar' and show me the latest 5 articles." "Crawl all history for 'Foo Bar' (61 articles total)." "Show me what's new in 'Foo Bar' today." "Fetch the latest article and summarize it in 3 bullets." "How much daily quota have I used?" ``` The LLM chooses the right tool. Full crawl: LLM walks `list_articles_page` itself. Incremental: server-side loop in `crawl_incremental`. ## Configuration (env vars) | Var | Default | Effect | |---|---|---| | `WECHAT_MP_MCP_DAILY_LIMIT` | `150` | Daily backend-call cap (WeChat's own limit is ~200/day per account — stay below) | | `WECHAT_MP_MCP_WORK_HOURS` | `8-23` | Local-time window for `crawl_incremental`. Set `0-24` to disable | | `WECHAT_MP_MCP_HOME` | `~/.config/wechat-mp-mcp` | Where to put `auth.json` | | `WECHAT_MP_MCP_DB` | `$HOME/wechat.db` | SQLite database path | ## Anti-detection A crawler hitting a fixed-interval pagination is the easiest pattern to flag. This server already does: - **Jittered delays**: `1.5s * [0.7, 2.0]` between pages, with ~8% chance of a 30-90s "tea break" - **Random page sizes**: 3-6 articles per request (biased to 5) - **Daily quota cap**: hard stop at 150 (25% buffer below WeChat's ~200) - **Work-hours gate**: `crawl_incremental` refuses outside 8am-11pm by default — real account operators don't run at 3am - **Realistic headers**: `Referer` mimics the article editor page, `X-Requested-With: XMLHttpRequest` - **Public article pages don't count**: bodies are fetched from public URLs, not the rate-limited backend You can still get rate-limited if you crawl aggressively. The 1-2h cookie expiry is normal session timeout, not a punishment. ## Risks - The subscription-account search interface is **undocumented**. WeChat can change it at any time; expect the request shape to need re-tuning every few months. - Read counts / likes / "看一看" are **not** available through this path. Those require intercepting the WeChat App's traffic (out of scope). - Use a **dedicated subscription account** for crawling — don't use one you actively operate. Worst case is a 24h freq-control lock on the search interface; the account itself isn't banned. - **Don't share your `auth.json`**. If WeChat sees the same session from multiple IPs, the account gets flagged as compromised. ## Storage SQLite at `~/.config/wechat-mp-mcp/wechat.db` by default. Tables: - `account(fakeid PK, nickname, alias, ...)` - `article(link PK, fakeid, title, update_time, body_markdown, ...)` - `quota(date PK, count)` — per-day API counter Inspect with any SQLite client. URL is the article's primary key, so re-crawling never produces duplicates. ## Tests ```bash .venv/bin/python tests/test_flows.py # 29 offline checks (no auth needed) .venv/bin/python tests/live_check.py # E2E against real WeChat (1 search + 1 list + 1 fetch) .venv/bin/python tests/live_crawl.py <fakeid> # Live incremental crawl ``` Live tests require a valid `auth.json`. `live_check.py` uses `WECHAT_MP_TEST_QUERY` env var (default: `央视新闻`) or first CLI arg for the target account. ## License MIT — see [LICENSE](LICENSE).