Skip to content
Back to search

wechat-to-md

SkillWorks with Claude CodeGitHub

Convert WeChat Official Account (微信公众号) articles to clean Markdown files with locally downloaded images.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bzd6661--wechat-article-for-ai/badge.svg)](/listings/bzd6661--wechat-article-for-ai)

HTML

<a href="/listings/bzd6661--wechat-article-for-ai"><img src="/api/listings/bzd6661--wechat-article-for-ai/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 98 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: wechat-to-md
  3. description: Convert WeChat Official Account (微信公众号) articles to clean Markdown files with locally downloaded images.
  4. ---
  5. # WeChat Article to Markdown Converter
  6. ## What this tool does
  7. Converts WeChat public account articles into clean Markdown files with:
  8. - YAML frontmatter (title, author, date, source URL)
  9. - Locally downloaded images
  10. - Preserved code blocks with language detection
  11. - Audio/video reference extraction
  12. - Clean formatting (no WeChat UI noise)
  13. ## Prerequisites
  14. - Python 3.10+
  15. - Install dependencies: `pip install -r requirements.txt`
  16. - Camoufox browser will be auto-downloaded on first run
  17. ## Usage
  18. ### CLI (single article)
  19. ```bash
  20. python main.py "https://mp.weixin.qq.com/s/ARTICLE_ID"
  21. ```
  22. ### CLI (batch from file)
  23. ```bash
  24. python main.py -f urls.txt -o ./output -v
  25. ```
  26. ### CLI Options
  27. | Flag | Description |
  28. |------|-------------|
  29. | `-f FILE` | Text file with URLs (one per line) |
  30. | `-o DIR` | Output directory (default: ./output) |
  31. | `-c N` | Image download concurrency (default: 5) |
  32. | `--no-images` | Skip image download, keep remote URLs |
  33. | `--no-headless` | Show browser (for solving CAPTCHAs) |
  34. | `--force` | Overwrite existing output |
  35. | `--no-frontmatter` | Use blockquote metadata instead of YAML |
  36. | `-v` | Verbose/debug logging |
  37. ### MCP Server
  38. Run as an MCP server for AI tool integration:
  39. ```bash
  40. python mcp_server.py
  41. ```
  42. Exposes two tools:
  43. - `convert_article(url, output_dir, download_images, concurrency, use_frontmatter)` — Convert a single article
  44. - `batch_convert(urls, output_dir, download_images, concurrency)` — Convert multiple articles
  45. ### MCP Configuration (for claude_desktop_config.json or similar)
  46. ```json
  47. {
  48. "mcpServers": {
  49. "wechat-to-md": {
  50. "command": "python",
  51. "args": ["mcp_server.py"],
  52. "cwd": "<path-to-this-project>"
  53. }
  54. }
  55. }
  56. ```
  57. ## Output Structure
  58. ```
  59. output/
  60. <article-title>/
  61. <article-title>.md # Markdown file with YAML frontmatter
  62. images/
  63. img_001.png
  64. img_002.jpg
  65. ...
  66. ```
  67. ## Common Issues
  68. - **CAPTCHA/verification page**: Run with `--no-headless` to manually solve the CAPTCHA in the browser window, then retry.
  69. - **Empty content**: WeChat may rate-limit requests. Wait a few minutes and try again.
  70. - **Image download failures**: Failed images keep their remote URLs in the markdown. Re-run with `--force` to retry.
  71. ## Limitations
  72. - Only supports articles from `mp.weixin.qq.com`
  73. - Requires a working internet connection and the ability to run a headless browser
  74. - WeChat may block automated access; Camoufox helps evade detection but is not guaranteed
README.md · README · 255 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # wechat-article-for-ai
  2. [English](#english) | [中文](#中文)
  3. ---
  4. ## English
  5. 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).
  6. ### Features
  7. - **Anti-detection scraping** — Uses [Camoufox](https://github.com/nichochar/camoufox) (stealth Firefox) to bypass WeChat's bot detection
  8. - **Smart page loading** — `networkidle` wait instead of hardcoded sleep
  9. - **Retry logic** — 3× exponential backoff for page fetching, 3× linear backoff for image downloads
  10. - **CAPTCHA detection** — Explicit detection with actionable error messages
  11. - **Batch processing** — Multiple URLs via args or file input
  12. - **Image localization** — Concurrent async downloads with Content-Type based extension inference
  13. - **Code block preservation** — Language detection, CSS counter garbage filtering
  14. - **Media extraction** — Handles WeChat's `<mpvoice>` audio and `<mpvideo>` video elements
  15. - **YAML frontmatter** — Structured metadata (title, author, date, source)
  16. - **MCP server** — Expose as tools for any MCP-compatible AI client
  17. - **SKILL.md** — Ready for Claude Code skill integration
  18. ### Installation
  19. ```bash
  20. git clone https://github.com/bzd6661/wechat-article-for-ai.git
  21. cd wechat-article-for-ai
  22. pip install -r requirements.txt
  23. ```
  24. > Camoufox browser will be auto-downloaded on first run.
  25. ### Usage
  26. #### CLI — Single Article
  27. ```bash
  28. python main.py "https://mp.weixin.qq.com/s/ARTICLE_ID"
  29. ```
  30. #### CLI — Batch from File
  31. ```bash
  32. python main.py -f urls.txt -o ./output -v
  33. ```
  34. #### CLI Options
  35. | Flag | Description |
  36. |------|-------------|
  37. | `urls` | One or more WeChat article URLs |
  38. | `-f, --file FILE` | Text file with URLs (one per line, `#` for comments) |
  39. | `-o, --output DIR` | Output directory (default: `./output`) |
  40. | `-c, --concurrency N` | Max concurrent image downloads (default: 5) |
  41. | `--no-images` | Skip image download, keep remote URLs |
  42. | `--no-headless` | Show browser window (for solving CAPTCHAs) |
  43. | `--force` | Overwrite existing output |
  44. | `--no-frontmatter` | Use blockquote metadata instead of YAML frontmatter |
  45. | `-v, --verbose` | Enable debug logging |
  46. #### MCP Server
  47. Run as an MCP server for AI tool integration:
  48. ```bash
  49. python mcp_server.py
  50. ```
  51. **Tools exposed:**
  52. - `convert_article` — Convert a single WeChat article to Markdown
  53. - `batch_convert` — Convert multiple articles in one call
  54. **MCP client configuration** (e.g. `claude_desktop_config.json`):
  55. ```json
  56. {
  57. "mcpServers": {
  58. "wechat-to-md": {
  59. "command": "python",
  60. "args": ["mcp_server.py"],
  61. "cwd": "/path/to/wechat-article-for-ai"
  62. }
  63. }
  64. }
  65. ```
  66. ### Output Structure
  67. ```
  68. output/
  69. <article-title>/
  70. <article-title>.md
  71. images/
  72. img_001.png
  73. img_002.jpg
  74. ...
  75. ```
  76. ### Project Structure
  77. ```
  78. wechat_to_md/
  79. __init__.py # Package init, public API
  80. errors.py # CaptchaError, NetworkError, ParseError
  81. utils.py # Logging, filename sanitizer, timestamp, image ext inference
  82. scraper.py # Camoufox + networkidle + retry with exponential backoff
  83. parser.py # BeautifulSoup: metadata, code blocks, media, noise removal
  84. converter.py # markdownify + YAML frontmatter + image URL replacement
  85. downloader.py # httpx async + retry per image + Content-Type inference
  86. cli.py # argparse CLI with batch support
  87. mcp_server.py # FastMCP server with convert_article / batch_convert
  88. main.py # CLI entry point
  89. mcp_server.py # MCP server entry point
  90. SKILL.md # AI skill definition
  91. ```
  92. ### Troubleshooting
  93. | Problem | Solution |
  94. |---------|----------|
  95. | CAPTCHA / verification page | Run with `--no-headless` to solve manually |
  96. | Empty content | WeChat may be rate-limiting; wait and retry |
  97. | Image download failures | Failed images keep remote URLs; re-run with `--force` |
  98. ### License
  99. MIT
  100. ---
  101. ## 中文
  102. 一个模块化的 Python 工具,将微信公众号文章转换为干净的 Markdown 文件并下载图片到本地。同时支持人工使用(CLI)和 AI 智能体集成(MCP 服务器 + SKILL.md)。
  103. ### 功能特点
  104. - **反检测抓取** — 使用 [Camoufox](https://github.com/nichochar/camoufox)(隐身 Firefox)绕过微信的反爬机制
  105. - **智能页面等待** — 使用 `networkidle` 替代硬编码的 sleep
  106. - **重试机制** — 页面加载 3 次指数退避重试,图片下载 3 次线性退避重试
  107. - **验证码检测** — 明确识别验证码页面并给出可操作的错误提示
  108. - **批量处理** — 支持多个 URL 参数或从文件读取
  109. - **图片本地化** — 异步并发下载,基于 Content-Type 推断图片格式
  110. - **代码块保留** — 自动检测编程语言,过滤 CSS 计数器垃圾文本
  111. - **媒体提取** — 处理微信的 `<mpvoice>` 音频和 `<mpvideo>` 视频元素
  112. - **YAML 元数据** — 结构化的 frontmatter(标题、作者、日期、来源)
  113. - **MCP 服务器** — 暴露为工具,供任何 MCP 兼容的 AI 客户端调用
  114. - **SKILL.md** — 可直接作为 Claude Code 技能使用
  115. ### 安装
  116. ```bash
  117. git clone https://github.com/bzd6661/wechat-article-for-ai.git
  118. cd wechat-article-for-ai
  119. pip install -r requirements.txt
  120. ```
  121. > Camoufox 浏览器会在首次运行时自动下载。
  122. ### 使用方法
  123. #### CLI — 单篇文章
  124. ```bash
  125. python main.py "https://mp.weixin.qq.com/s/文章ID"
  126. ```
  127. #### CLI — 批量转换
  128. ```bash
  129. python main.py -f urls.txt -o ./output -v
  130. ```
  131. #### CLI 参数
  132. | 参数 | 说明 |
  133. |------|------|
  134. | `urls` | 一个或多个微信文章链接 |
  135. | `-f, --file 文件` | 包含 URL 的文本文件(每行一个,`#` 为注释) |
  136. | `-o, --output 目录` | 输出目录(默认:`./output`) |
  137. | `-c, --concurrency N` | 图片下载最大并发数(默认:5) |
  138. | `--no-images` | 跳过图片下载,保留远程链接 |
  139. | `--no-headless` | 显示浏览器窗口(用于手动解决验证码) |
  140. | `--force` | 覆盖已有的输出目录 |
  141. | `--no-frontmatter` | 使用引用块格式的元数据,而非 YAML frontmatter |
  142. | `-v, --verbose` | 启用调试日志 |
  143. #### MCP 服务器
  144. 作为 MCP 服务器运行,供 AI 工具集成:
  145. ```bash
  146. python mcp_server.py
  147. ```
  148. **暴露的工具:**
  149. - `convert_article` — 转换单篇微信文章为 Markdown
  150. - `batch_convert` — 批量转换多篇文章
  151. **MCP 客户端配置**(如 `claude_desktop_config.json`):
  152. ```json
  153. {
  154. "mcpServers": {
  155. "wechat-to-md": {
  156. "command": "python",
  157. "args": ["mcp_server.py"],
  158. "cwd": "/path/to/wechat-article-for-ai"
  159. }
  160. }
  161. }
  162. ```
  163. ### 输出结构
  164. ```
  165. output/
  166. <文章标题>/
  167. <文章标题>.md
  168. images/
  169. img_001.png
  170. img_002.jpg
  171. ...
  172. ```
  173. ### 项目结构
  174. ```
  175. wechat_to_md/
  176. __init__.py # 包初始化,公共 API
  177. errors.py # CaptchaError, NetworkError, ParseError
  178. utils.py # 日志、文件名清理、时间戳、图片格式推断
  179. scraper.py # Camoufox + networkidle + 指数退避重试
  180. parser.py # BeautifulSoup:元数据、代码块、媒体、噪音移除
  181. converter.py # markdownify + YAML frontmatter + 图片 URL 替换
  182. downloader.py # httpx 异步 + 逐图重试 + Content-Type 推断
  183. cli.py # argparse CLI,支持批量处理
  184. mcp_server.py # FastMCP 服务器
  185. main.py # CLI 入口
  186. mcp_server.py # MCP 服务器入口
  187. SKILL.md # AI 技能定义文件
  188. ```
  189. ### 常见问题
  190. | 问题 | 解决方法 |
  191. |------|----------|
  192. | 出现验证码 / 环境异常 | 使用 `--no-headless` 手动解决验证码 |
  193. | 内容为空 | 微信可能在限流,等几分钟再试 |
  194. | 图片下载失败 | 失败的图片会保留远程链接,用 `--force` 重新运行 |
  195. ### 许可证
  196. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.