crawl-mcp

完整的微信文章抓取MCP服务器 - 基于Model Context Protocol (MCP)的智能网页抓取工具，专为Cursor IDE和AI工具设计。

GitHub

GitHub Stars

User Rating

Not Rated

Forks

Issues

Views

Favorites

README

Crawl-MCP Server

🚀 真正能下载图片的微信文章抓取工具 - 基于Model Context Protocol (MCP)的智能抓取服务器，专为Cursor IDE和AI工具设计。

🎉 v1.1.0 重大升级：从"指令生成器"升级为"真正下载工具"，支持完整的图片本地化！

✨ 主要特性

🎯 核心功能 (v1.1.0)

真正的图片下载: ✅ 实际下载微信图片，不只是生成指令
双模式设计: 指令模式（学习用）+ 自动模式（效率用）
完整本地化: 图片下载 + 路径更新 + 离线可用的Markdown文档
智能处理: 微信域名识别、正确Headers、并发控制、重试机制

🔧 技术特色 (v1.1.0)

专业图片处理:
- 🎯 微信图片域名识别（mmbiz.qpic.cn）
- 🎯 正确的HTTP Headers（Referer, User-Agent）
- 🎯 wx_fmt参数处理（jpeg, png, gif）
- 🎯 并发控制（同时下载3张）+ 重试机制
MCP协议支持: 完整的Model Context Protocol实现
模块化架构: ImageDownloader + ArticleProcessor + CrawlTool
TypeScript支持: 完整的类型定义和编译支持
Node.js 18+: 使用内置fetch API，无额外HTTP库依赖

🎮 Cursor IDE集成

一键安装: npx crawl-mcp-server@1.1.0
开箱即用: 无需复杂配置，直接可用
AI工具支持: 在Cursor中直接使用AI进行完整抓取
工具自动识别: Agent自动调用相关抓取工具

🚀 快速开始

💻 安装使用

方法1: npx直接运行（推荐）

# 使用最新的v1.1.0版本
npx crawl-mcp-server@1.1.0

方法2: 全局安装

npm install -g crawl-mcp-server@1.1.0
crawl-mcp-server

方法3: 项目本地安装

npm install crawl-mcp-server@1.1.0
npx crawl-mcp-server

💡 提示: 推荐使用 @1.1.0 版本，确保获得最新的图片下载功能

🔌 Cursor IDE配置

创建MCP配置文件 在项目根目录创建 .cursor/mcp.json:

{
  "mcpServers": {
    "crawl-mcp": {
      "command": "npx",
      "args": ["-y", "crawl-mcp-server@1.1.0"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

重启Cursor 重启Cursor让配置生效

开始使用 在Cursor中直接使用AI助手进行网页抓取：

指令模式（学习推荐）：

请使用crawl mcp抓取这篇微信文章：https://mp.weixin.qq.com/s/xxxxx

自动模式（效率优先）：

我已经获取了HTML内容，请使用crawl mcp自动模式处理并下载图片

🛠️ MCP工具说明

1. crawl_wechat_article

单篇文章抓取工具

参数:

url (必需): 微信文章链接
outputFormat (可选): 输出格式 (markdown/json/html，默认: markdown)
strategy (可选): 抓取策略 (basic/conservative/fast，默认: basic)
includeImages (可选): 是否包含图片 (默认: true)

示例:

{
  "url": "https://mp.weixin.qq.com/s/example123",
  "outputFormat": "markdown",
  "strategy": "basic",
  "includeImages": true
}

2. crawl_wechat_batch

批量文章抓取工具

参数:

urls (必需): 文章链接数组
outputFormat (可选): 输出格式
strategy (可选): 抓取策略
maxConcurrent (可选): 最大并发数 (默认: 3)

示例:

{
  "urls": [
    "https://mp.weixin.qq.com/s/example1",
    "https://mp.weixin.qq.com/s/example2"
  ],
  "outputFormat": "markdown",
  "maxConcurrent": 2
}

3. crawl_get_status

状态查询工具

参数:

sessionId (可选): 会话ID，不提供则返回所有会话状态

⚙️ 抓取策略说明

策略	速度	稳定性	适用场景
fast	⚡ 最快	🔸 一般	网络良好，页面简单
basic	🚀 中等	⭐ 平衡	大多数情况（推荐）
conservative	🐌 较慢	💎 最稳定	网络不稳定，复杂页面

📦 项目结构

crawl-mcp/
├── src/
│   ├── core/              # 核心模块
│   │   ├── CrawlMCPServer.ts    # MCP服务器
│   │   ├── CallOrchestrator.ts  # 调用编排器
│   │   └── StateManager.ts     # 状态管理
│   ├── adapters/          # 输出适配器
│   │   ├── MCPOutputAdapter.ts  # MCP格式转换
│   │   └── FileOutputAdapter.ts # 文件输出
│   ├── clients/           # 客户端
│   │   └── PlaywrightMCPClient.ts # Playwright客户端
│   ├── processors/        # 内容处理器
│   │   ├── ContentExtractor.ts  # 内容提取
│   │   ├── MarkdownConverter.ts # Markdown转换
│   │   └── ImageProcessor.ts    # 图片处理
│   ├── tools/             # MCP工具定义
│   ├── types/             # TypeScript类型
│   └── utils/             # 工具函数
├── docs/                  # 文档
├── examples/              # 示例代码
└── tests/                 # 测试文件

🧪 开发和测试

安装依赖

pnpm install

构建项目

pnpm build

运行测试

pnpm test

本地开发

pnpm dev

📊 测试覆盖

✅ 25个测试 全部通过
🧪 单元测试: 核心组件功能验证
🔗 集成测试: MCP协议完整性测试
📋 配置测试: 所有配置文件验证

🤝 贡献指南

Fork 这个仓库
创建你的特性分支 (git checkout -b feature/AmazingFeature)
提交你的更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启一个 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🔗 相关链接

📦 NPM包
🐙 GitHub仓库
📖 API文档
🛠️ 故障排除
📋 发布指南

📞 支持

如果你遇到任何问题或有建议，请：

🐛 提交Issue
💬 参与讨论
📧 联系开发者

⭐ 如果这个项目对你有帮助，请给我们一个星标！

Made with ❤️ by wutongci

Author Information

梧桐

mobvista广州

GitHub

Followers

Repositories

Gists

Total Contributions