---

name: wechat-to-md description: Convert WeChat Official Account (微信公众号) articles to clean Markdown files with locally downloaded images.

WeChat Article to Markdown Converter

What this tool does

Converts WeChat public account articles into clean Markdown files with:

• YAML frontmatter (title, author, date, source URL)
• Locally downloaded images
• Preserved code blocks with language detection
• Audio/video reference extraction
• Clean formatting (no WeChat UI noise)

Prerequisites

• Python 3.10+
• Install dependencies: 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

| Flag | Description | |------|-------------| | -f FILE | Text file with URLs (one per line) | | -o DIR | Output directory (default: ./output) | | -c N | Image download concurrency (default: 5) | | --no-images | Skip image download, keep remote URLs | | --no-headless | Show browser (for solving CAPTCHAs) | | --force | Overwrite existing output | | --no-frontmatter | Use blockquote metadata instead of YAML | | -v | Verbose/debug logging |

MCP Server

Run as an MCP server for AI tool integration:

python mcp_server.py

Exposes two tools:

• convert_article(url, output_dir, download_images, concurrency, use_frontmatter) — Convert a single article
• batch_convert(urls, output_dir, download_images, concurrency) — Convert multiple articles

MCP Configuration (for claude_desktop_config.json or similar)

{
  "mcpServers": {
    "wechat-to-md": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": "<path-to-this-project>"
    }
  }
}

Output Structure

output/
  <article-title>/
    <article-title>.md    # Markdown file with YAML frontmatter
    images/
      img_001.png
      img_002.jpg
      ...

Common Issues

• CAPTCHA/verification page: Run with --no-headless to manually solve the CAPTCHA in the browser window, then retry.
• Empty content: WeChat may rate-limit requests. Wait a few minutes and try again.
• Image download failures: Failed images keep their remote URLs in the markdown. Re-run with --force to retry.

Limitations

• Only supports articles from mp.weixin.qq.com
• Requires a working internet connection and the ability to run a headless browser
• WeChat may block automated access; Camoufox helps evade detection but is not guaranteed