Wechat Parser MCP

微信公众号文章解析 MCP Server

微信公众号文章解析 MCP Server 是一个专为 AI Agent 设计的工具，用于解析和提取微信公众号文章内容。通过 Model Context Protocol (MCP)，它可以与 Claude、Cursor 等 AI 助手无缝集成，让 AI 能够访问和分析微信公众号文章。

✨ 核心特性

🎯 Agent-Centric 设计

• 任务导向：工具名称反映具体任务（parse_wechat_article）
• 完整工作流：从URL输入到结构化内容输出的完整流程
• 智能默认值：减少 Agent 的参数指定负担

🚀 强大的功能

• 📰 完整内容提取：标题、作者、正文、图片、视频
• 🔄 多种提取方法：HTTP直接请求 + 浏览器自动化（Playwright）
• 📊 多种输出格式：JSON（结构化）和 Markdown（易读）
• 🎯 灵活控制：concise/detailed 模式，节省上下文
• ⚡ 自动降级：HTTP失败时自动切换到浏览器方法
• 🧹 内容清理：自动移除广告和无关内容

🛡️ 完善的错误处理

• 可操作的错误信息
• 智能建议和解决方案
• 详细的错误类型分类

🚀 快速开始

安装

方法1：从源码安装（推荐）

# 克隆仓库
git clone https://github.com/yourusername/wechat-parser-mcp.git
cd wechat-parser-mcp

# 安装
pip install -e .

# 如果需要浏览器自动化功能（可选但推荐）
pip install -e ".[browser]"
playwright install chromium

方法2：使用 pip（如果已发布到PyPI）

pip install wechat-parser-mcp

# 可选：安装浏览器支持
pip install "wechat-parser-mcp[browser]"
playwright install chromium

配置

在 Claude Desktop 中使用

编辑 Claude Desktop 配置文件（位置因系统而异）：

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "wechat-parser": {
      "command": "python",
      "args": [
        "-m",
        "wechat_parser_mcp.server"
      ],
      "env": {}
    }
  }
}

或者，如果使用虚拟环境：

{
  "mcpServers": {
    "wechat-parser": {
      "command": "/path/to/venv/bin/python",
      "args": [
        "-m",
        "wechat_parser_mcp.server"
      ]
    }
  }
}

在 Cursor 中使用

1. 打开 Cursor 设置
2. 找到 MCP 配置
3. 添加服务器配置（类似 Claude Desktop）

使用

启动 Claude Desktop 或 Cursor，然后可以直接使用：

请帮我解析这篇微信公众号文章：
https://mp.weixin.qq.com/s/xxxxx

或者在 MCP Inspector 中测试：

fastmcp dev src/wechat_parser_mcp/server.py

📖 使用示例

基本用法

输入：

{
  "url": "https://mp.weixin.qq.com/s/nayiY9wflpHm9PM5Aoi-hA"
}

输出（JSON格式）：

{
  "success": true,
  "url": "https://mp.weixin.qq.com/s/...",
  "title": "文章标题",
  "author": "作者名称",
  "publish_time": "2024-01-01T12:00:00",
  "content": "文章正文内容...",
  "images": [
    {
      "url": "https://example.com/image.jpg",
      "alt": "图片描述",
      "index": 1,
      "width": "800",
      "height": "600"
    }
  ],
  "metadata": {
    "word_count": 2500,
    "reading_time": "12分钟",
    "extract_method": "http"
  }
}

高级用法

Markdown格式，详细模式：

{
  "url": "https://mp.weixin.qq.com/s/xxx",
  "format": "markdown",
  "detail": "detailed",
  "extract_method": "auto"
}

强制使用浏览器方法：

{
  "url": "https://mp.weixin.qq.com/s/xxx",
  "extract_method": "browser"
}

🔧 配置选项

环境变量

创建 .env 文件（可选）：

# HTTP请求超时时间（秒）
REQUEST_TIMEOUT=30

# 浏览器类型（chromium/firefox/webkit）
BROWSER_TYPE=chromium

# 是否启用缓存（暂未实现）
ENABLE_CACHE=true
CACHE_TTL=3600

参数说明

🎯 提取方法说明

auto（推荐）

自动选择最佳方法：

1. 先尝试HTTP（快速）
2. 失败时自动降级到浏览器（稳定）

优点： 无需关心技术细节，自动优化

http

直接HTTP请求：

• ⚡ 速度快
• 💚 资源消耗低
• ⚠️ 可能遇到反爬虫限制

browser

浏览器自动化（需要Playwright）：

• ✅ 绕过反爬虫
• ✅ 支持JavaScript渲染
• ⏱️ 速度较慢
• 💾 资源消耗较大

📚 工具说明

parse_wechat_article

解析微信公众号文章并提取内容。

功能：

• ✅ URL验证和解析
• ✅ 内容提取（标题、作者、正文、图片、视频）
• ✅ 格式转换（HTML → Markdown）
• ✅ 内容清理（移除广告）
• ✅ 自动降级（HTTP失败时切换浏览器）

使用场景：

• 快速获取文章核心内容
• 需要完整文章内容进行分析
• 提取文章中的图片和视频资源
• 批量处理多篇文章

🛠️ 开发

开发环境设置

# 克隆仓库
git clone https://github.com/yourusername/wechat-parser-mcp.git
cd wechat-parser-mcp

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # macOS/Linux
# 或 venv\Scripts\activate  # Windows

# 安装开发依赖
pip install -e ".[dev,browser]"
playwright install chromium

运行测试

# 基础功能测试
python test_basic.py

# 增强功能测试
python test_enhancements.py

# Phase 3功能测试
python test_phase3.py

# 集成测试
python test_integration.py

开发模式

# 启动MCP Inspector
fastmcp dev src/wechat_parser_mcp/server.py

📁 项目结构

wechat_parser_mcp/
├── src/
│   └── wechat_parser_mcp/
│       ├── __init__.py
│       ├── server.py              # MCP Server 主文件
│       ├── tools/
│       │   ├── __init__.py
│       │   └── parser.py          # 文章解析工具
│       └── utils/
│           ├── __init__.py
│           ├── url_validator.py   # URL验证和解析
│           ├── content_extractor.py  # 内容提取器
│           ├── http_client.py     # HTTP请求客户端
│           ├── browser_extractor.py  # 浏览器自动化
│           ├── formatters.py      # 响应格式化
│           └── errors.py          # 错误处理
├── pyproject.toml                 # 项目配置
├── README.md                       # 项目说明
├── LICENSE                         # MIT许可证
├── CHANGELOG.md                    # 更新日志
├── .gitignore                      # Git忽略文件
└── tests/                          # 测试文件
    ├── test_basic.py
    ├── test_enhancements.py
    ├── test_integration.py
    └── test_phase3.py

🐛 故障排除

常见问题

Q: 导入错误 attempted relative import

A: 确保已安装包：

pip install -e .

Q: Playwright未安装错误

A: 安装Playwright：

pip install playwright
playwright install chromium

Q: 遇到403/429错误

A: 使用浏览器方法：

{
  "extract_method": "browser"
}

或使用auto模式自动降级。

Q: 文章解析失败

A: 检查：

1. URL格式是否正确
2. 文章是否需要登录
3. 网络连接是否正常

更多故障排除信息，请查看 TROUBLESHOOTING.md

📄 许可证

本项目采用 MIT License 许可证。

🤝 贡献

欢迎贡献！请查看 CONTRIBUTING.md（如果存在）了解贡献指南。

📝 更新日志

详细的更新日志请查看 CHANGELOG.md

🔗 相关资源

• MCP 协议规范
• FastMCP 文档
• BeautifulSoup 文档
• Playwright 文档

⚠️ 注意事项

1. 法律合规：请遵守相关法律法规，仅用于合法用途
2. 使用限制：某些文章可能需要登录才能访问
3. 反爬虫：微信公众号有反爬虫机制，建议使用auto模式自动处理
4. 资源消耗：浏览器方法会消耗更多资源，建议仅在必要时使用

💡 最佳实践

1. 默认使用auto模式：让系统自动选择最佳方法
2. 合理使用详细程度：concise模式节省上下文，detailed模式获取完整信息
3. 检查返回的extract_method：了解系统实际使用的方法
4. 查看错误建议：遇到问题时查看错误信息中的解决建议

Made with ❤️ for AI Agents