FreeCrawl MCP Server

FreeCrawl MCP服务器

用于web抓取和文档处理的生产就绪模型上下文协议（MCP）服务器，旨在作为Firecrawl的自托管替代品。

🚀 特性

• 启用JavaScript的网页抓取 有编剧和反侦查措施
• 文档处理 支持多种格式的回退
• 并行批处理 具有可配置的限制
• 智能缓存 使用SQLite后端
• 速率限制 每个域名
• 全面的错误处理 具有重试逻辑
• 简易安装 通过 uvx 或本地开发设置
• 健康监测 和指标收集

MCP配置（使用 uvx)

{
  "mcpServers": {
    "freecrawl": {
      "command": "uvx",
      "args": ["freecrawl-mcp"],
    }
  }
}

📦 安装与使用

uvx快速入门（推荐）

使用FreeCrawl最简单的方法是 uvx，它自动管理依赖关系：

# Install browsers on first run
uvx freecrawl-mcp --install-browsers

# Test functionality
uvx freecrawl-mcp --test

地方发展设置

对于本地开发或定制：

1. 从GitHub克隆：

   git clone https://github.com/dylan-gluck/freecrawl-mcp.git
   cd freecrawl-mcp

1. 设置环境：

   # Sync dependencies
   uv sync

   # Install browser dependencies
   uv run freecrawl-mcp --install-browsers

   # Run tests
   uv run freecrawl-mcp --test

1. 运行服务器：

   uv run freecrawl-mcp

🛠 配置

使用环境变量配置FreeCrawl：

基本配置

# Transport (stdio for MCP, http for REST API)
export FREECRAWL_TRANSPORT=stdio

# Browser pool settings
export FREECRAWL_MAX_BROWSERS=3
export FREECRAWL_HEADLESS=true

# Concurrency limits
export FREECRAWL_MAX_CONCURRENT=10
export FREECRAWL_MAX_PER_DOMAIN=3

# Cache settings
export FREECRAWL_CACHE=true
export FREECRAWL_CACHE_DIR=/tmp/freecrawl_cache
export FREECRAWL_CACHE_TTL=3600
export FREECRAWL_CACHE_SIZE=536870912  # 512MB

# Rate limiting
export FREECRAWL_RATE_LIMIT=60  # requests per minute

# Logging
export FREECRAWL_LOG_LEVEL=INFO

安全设置

# API authentication (optional)
export FREECRAWL_REQUIRE_API_KEY=false
export FREECRAWL_API_KEYS=key1,key2,key3

# Domain blocking
export FREECRAWL_BLOCKED_DOMAINS=localhost,127.0.0.1

# Anti-detection
export FREECRAWL_ANTI_DETECT=true
export FREECRAWL_ROTATE_UA=true

🔧 MCP工具

FreeCrawl提供以下MCP工具：

freecrawl_scrape

使用高级选项从单个URL中抓取内容。

参数：

• url （string）：要抓取的URL
• formats （数组）：输出格式- ["markdown", "html", "text", "screenshot", "structured"]
• javascript （boolean）：启用JavaScript执行（默认值：true）
• wait_for （string，可选）：CSS选择器或等待时间（ms）
• anti_bot （boolean）：启用反检测措施（默认值：true）
• headers （对象，可选）：自定义HTTP标头
• cookies （对象，可选）：自定义Cookie
• cache （boolean）：如果可用，则使用缓存结果（默认值：true）
• timeout （number）：总超时时间（毫秒）（默认值：30000）

例子：

{
  "name": "freecrawl_scrape",
  "arguments": {
    "url": "https://example.com",
    "formats": ["markdown", "screenshot"],
    "javascript": true,
    "wait_for": "2000"
  }
}

freecrawl_batch_scrape

同时删除多个URL。

参数：

• urls （数组）：要抓取的URL列表（最多100个）
• concurrency （number）：最大并发请求数（默认值：5）
• formats （数组）：输出格式（默认值： ["markdown"])
• common_options （object，可选）：应用于所有URL的选项
• continue_on_error （boolean）：如果单个URL失败，则继续（默认值：true）

例子：

{
  "name": "freecrawl_batch_scrape",
  "arguments": {
    "urls": [
      "https://example.com/page1",
      "https://example.com/page2"
    ],
    "concurrency": 3,
    "formats": ["markdown", "text"]
  }
}

freecrawl_extract

使用模式驱动方法提取结构化数据。

参数：

• url （string）：从中提取数据的URL
• schema （对象）：JSON模式或Pydantic模型定义
• prompt （字符串，可选）：自定义提取说明
• validation （boolean）：根据模式验证（默认值：true）
• multiple （boolean）：提取多个匹配项（默认值：false）

例子：

{
  "name": "freecrawl_extract",
  "arguments": {
    "url": "https://example.com/product",
    "schema": {
      "type": "object",
      "properties": {
        "title": {"type": "string"},
        "price": {"type": "number"}
      }
    }
  }
}

freecrawl_process_document

使用OCR支持处理文档（PDF、DOCX等）。

参数：

• file_path （字符串，可选）：文档文件的路径
• url （字符串，可选）：下载文档的URL
• strategy （string）：处理策略- "fast", "hi_res", "ocr_only" （默认值：“hi_res”）
• formats （数组）：输出格式- ["markdown", "structured", "text"]
• languages （数组，可选）：OCR语言（例如。， ["eng", "fra"])
• extract_images （boolean）：提取嵌入图像（默认值：false）
• extract_tables （boolean）：提取和构造表（默认值：true）

例子：

{
  "name": "freecrawl_process_document",
  "arguments": {
    "url": "https://example.com/document.pdf",
    "strategy": "hi_res",
    "formats": ["markdown", "structured"]
  }
}

freecrawl_health_check

获取服务器运行状况和指标。

例子：

{
  "name": "freecrawl_health_check",
  "arguments": {}
}

🔄 与Claude Code集成

MCP配置

将FreeCrawl添加到MCP配置中：

使用uvx（推荐）：

{
  "mcpServers": {
    "freecrawl": {
      "command": "uvx",
      "args": ["freecrawl-mcp"]
    }
  }
}

使用本地开发设置：

{
  "mcpServers": {
    "freecrawl": {
      "command": "uv",
      "args": ["run", "freecrawl-mcp"],
      "cwd": "/path/to/freecrawl-mcp"
    }
  }
}

Prompts中的用法

Please scrape the content from https://example.com and extract the main article text in markdown format.

Claude Code将自动使用 freecrawl_scrape 获取和处理内容的工具。

🚀 性能和可扩展性

资源使用情况

• 记忆：~100MB基础+每个浏览器实例~50MB
• 中央处理器：在主动刮擦过程中适度使用
• 存储：缓存根据配置的限制增长

吞吐量

• 单个请求：典型响应时间为2-5秒
• 批量处理：10-50个并发请求，具体取决于配置
• 缓存命中率：重复内容为30%+

优化提示

1. 启用缓存 用于频繁访问的内容
2. 调整并发性 基于目标站点速率限制
3. 使用适当的格式 -markdown比截图更快
4. 配置速率限制 避免被阻塞

🛡 安全考虑

反检测

• 轮换用户代理
• 逼真的浏览器指纹
• 请求定时随机化
• 沙盒环境中的JavaScript执行

输入验证

• URL格式验证
• 私有IP阻止
• 域阻止列表支持
• 请求大小限制

资源保护

• 内存使用监控
• 浏览器池大小限制
• 请求超时强制
• 每个域的速率限制

🔧 故障排除

常见问题

调试模式

使用uvx：

export FREECRAWL_LOG_LEVEL=DEBUG
uvx freecrawl-mcp --test

地方发展：

export FREECRAWL_LOG_LEVEL=DEBUG
uv run freecrawl-mcp --test

📈 监测和可观察性

健康指标

• 浏览器池状态
• 内存和CPU使用率
• 缓存命中率
• 请求成功率
• 响应时间

日志记录

FreeCrawl提供具有可配置级别的结构化日志记录：

• 错误：严重故障
• 警告：可恢复的问题
• 信息：一般操作
• 调试：详细的故障排除

🔧 发展

运行测试

使用uvx：

# Basic functionality test
uvx freecrawl-mcp --test

地方发展：

# Basic functionality test
uv run freecrawl-mcp --test

编码结构

• 核心服务器: FreeCrawlServer 类
• 浏览器管理: BrowserPool 用于资源池
• 内容提取: ContentExtractor 采用多种策略
• 缓存: CacheManager 使用SQLite后端
• 速率限制: RateLimiter 使用令牌桶算法

📄 许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅技术规范。

🤝 贡献

1. 在以下位置分叉存储库https://github.com/dylan-gluck/freecrawl-mcp
2. 创建要素分支
3. 建立当地发展： uv sync
4. 运行测试： uv run freecrawl-mcp --test
5. 提交拉取请求

📚 技术规范

有关详细的技术信息，请参阅 ai_docs/FREECRAWL_TECHNICAL_SPEC.md.

______________________________________________________________________

FreeCrawl MCP服务器 -现代网络的自托管网络抓取🚀