wechat-article-for-ai

English | 中文

English

A modular Python tool that converts WeChat Official Account (微信公众号) articles into clean Markdown files with locally downloaded images. Designed for both human use (CLI) and AI agent integration (MCP server + SKILL.md).

Features

• Anti-detection scraping — Uses Camoufox (stealth Firefox) to bypass WeChat's bot detection
• Smart page loading — networkidle wait instead of hardcoded sleep
• Retry logic — 3× exponential backoff for page fetching, 3× linear backoff for image downloads
• CAPTCHA detection — Explicit detection with actionable error messages
• Batch processing — Multiple URLs via args or file input
• Image localization — Concurrent async downloads with Content-Type based extension inference
• Code block preservation — Language detection, CSS counter garbage filtering
• Media extraction — Handles WeChat's <mpvoice> audio and <mpvideo> video elements
• YAML frontmatter — Structured metadata (title, author, date, source)
• MCP server — Expose as tools for any MCP-compatible AI client
• SKILL.md — Ready for Claude Code skill integration

Installation

git clone https://github.com/bzd6661/wechat-article-for-ai.git
cd wechat-article-for-ai
pip install -r requirements.txt

Camoufox browser will be auto-downloaded on first run.

Usage

CLI — Single Article

python main.py "https://mp.weixin.qq.com/s/ARTICLE_ID"

CLI — Batch from File

python main.py -f urls.txt -o ./output -v

CLI Options

MCP Server

Run as an MCP server for AI tool integration:

python mcp_server.py

Tools exposed:

• convert_article — Convert a single WeChat article to Markdown
• batch_convert — Convert multiple articles in one call

MCP client configuration (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "wechat-to-md": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": "/path/to/wechat-article-for-ai"
    }
  }
}

Output Structure

output/
  <article-title>/
    <article-title>.md
    images/
      img_001.png
      img_002.jpg
      ...

Project Structure

wechat_to_md/
  __init__.py        # Package init, public API
  errors.py          # CaptchaError, NetworkError, ParseError
  utils.py           # Logging, filename sanitizer, timestamp, image ext inference
  scraper.py         # Camoufox + networkidle + retry with exponential backoff
  parser.py          # BeautifulSoup: metadata, code blocks, media, noise removal
  converter.py       # markdownify + YAML frontmatter + image URL replacement
  downloader.py      # httpx async + retry per image + Content-Type inference
  cli.py             # argparse CLI with batch support
  mcp_server.py      # FastMCP server with convert_article / batch_convert
main.py              # CLI entry point
mcp_server.py        # MCP server entry point
SKILL.md             # AI skill definition

Troubleshooting

License

MIT

中文

一个模块化的

... View full README on GitHub