Firecrawl Simple MCP Server

Firecrawl Simple MCP 服务

一个用于 Firecrawl Simple 的模型上下文协议（MCP）服务。Firecrawl Simple 是一款强大的网页抓取和站点映射工具，可让大语言模型（LLM）访问和处理网页内容。

项目链接

• GitHub 仓库
• npm 包

目录

• 先决条件
• 快速开始
• 功能
• 安装
• 使用方法
• 配置
• 可用工具
• 故障排除
• 关于抓取功能的说明
• 架构改进
• 开发
• 测试
• 贡献
• 许可证

先决条件

安装和使用 Firecrawl Simple MCP 服务前，请确保具备以下条件：

• 已安装 Node.js 16.x 或更高版本
• 可以访问正在运行的 Firecrawl Simple API 实例
• 具备安装全局 npm 包所需的权限（如需全局安装）

快速开始

# Install the package
npm install -g firecrawl-simple-mcp

# Run with default configuration
FIRECRAWL_API_URL=http://localhost:3002/v1 firecrawl-simple-mcp

# Test with a simple scrape request
curl -X POST http://localhost:3003/mcp/tool \
  -H "Content-Type: application/json" \
  -d '{"name":"firecrawl_scrape","arguments":{"url":"https://example.com"}}'

功能

• 网页抓取：抓取任意 URL 的内容，并支持 JavaScript 渲染。
• 网站映射：为指定网站生成站点地图。
• 简化的架构：优化代码库，采用一致的模式并改进错误处理。
• 类型安全：整个代码库均采用强类型，并通过 Zod 进行模式验证。
• 可配置：通过环境变量自定义行为。

安装

使用 npm

npm install -g firecrawl-simple-mcp

从源代码安装

git clone https://github.com/dsafonov/firecrawl-simple-mcp.git
cd firecrawl-simple-mcp
npm install
npm run build

使用方法

运行服务

# Basic usage with self-hosted Firecrawl Simple
FIRECRAWL_API_URL=http://localhost:3002/v1 firecrawl-simple-mcp

# With additional configuration
FIRECRAWL_API_URL=http://localhost:3002/v1 \
FIRECRAWL_LOG_LEVEL=DEBUG \
firecrawl-simple-mcp

配置

可以使用环境变量配置服务：

变量	描述	默认值
FIRECRAWL_API_URL	Firecrawl Simple API 的 URL	http://localhost:3002/v1
FIRECRAWL_API_KEY	用于身份验证的 API 密钥（如有需要）	-
FIRECRAWL_API_TIMEOUT	API 请求超时时间（毫秒）	30000
FIRECRAWL_SERVER_PORT	使用 SSE 传输时 MCP 服务的端口	3003
FIRECRAWL_TRANSPORT_TYPE	传输类型（stdio 或 sse）	stdio
FIRECRAWL_LOG_LEVEL	日志级别（DEBUG、INFO、WARN、ERROR）	INFO
FIRECRAWL_VERSION	版本标识符	1.0.0

与 Claude Desktop 配合使用

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "firecrawl-simple-mcp": {
      "command": "npx",
      "args": ["-y", "firecrawl-simple-mcp"],
      "env": {
        "FIRECRAWL_API_URL": "http://localhost:3002/v1"
      }
    }
  }
}

与 Cursor 配合使用

在 Cursor 中进行配置：

1. 打开 Cursor 设置
2. 前往 Features > MCP Servers
3. 点击“+ Add New MCP Server”
4. 输入以下内容：
   • 名称：“firecrawl-simple-mcp”（或使用你偏好的名称）
   • 类型：“command”
   • 命令：env FIRECRAWL_API_URL=http://localhost:3002/v1 npx -y firecrawl-simple-mcp

可用工具

1. 抓取工具（firecrawl_scrape）

抓取单个 URL 的内容，并支持 JavaScript 渲染。

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com",
    "formats": ["markdown", "html", "rawHtml"],
    "waitFor": 1000,
    "timeout": 30000,
    "includeTags": ["article", "main"],
    "excludeTags": ["nav", "footer"],
    "headers": {
      "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
      "Accept-Language": "en-US,en;q=0.9"
    },
    "mobile": false
  }
}

参数：

• url（必填）：要抓取的 URL。
• formats：要返回的输出格式数组。选项包括“markdown”、“html”和“rawHtml”。
• waitFor：等待 JavaScript 执行的时间（毫秒）。
• timeout：请求超时时间（毫秒）。
• includeTags：要包含在结果中的 HTML 标签。
• excludeTags：要从结果中排除的 HTML 标签。
• headers：随请求发送的自定义 HTTP 标头。
• mobile：是否使用移动设备视口。

2. 地图工具（firecrawl_map）

生成指定网站的站点地图。

{
  "name": "firecrawl_map",
  "arguments": {
    "url": "https://example.com",
    "search": "optional search term",
    "ignoreSitemap": true,
    "includeSubdomains": false,
    "limit": 5000
  }
}

参数：

• url（必需）：要映射的 URL。
• search：用于筛选 URL 的搜索词。
• ignoreSitemap：是否忽略 sitemap.xml。
• includeSubdomains：映射时是否包含子域名。
• limit：要映射的 URL 数量上限。

故障排除

常见错误及解决方案

连接问题

错误：Failed to connect to Firecrawl API at http://localhost:3002/v1

解决方案：

• 确认 Firecrawl Simple API 正在运行
• 检查 API URL 是否正确，包括 /v1 路径
• 确保没有网络限制阻止连接

身份验证错误

错误：Authentication failed: Invalid API key

解决方案：

• 确认 FIRECRAWL_API_KEY 正确
• 检查 API 是否需要身份验证
• 联系 API 管理员获取有效凭据

超时错误

错误：Request timed out after 30000ms

解决方案：

• 增大 FIRECRAWL_API_TIMEOUT 的值
• 检查目标网站是否响应缓慢或无响应
• 考虑使用 waitFor 参数，为 JavaScript 执行留出更多时间

速率限制

错误：Rate limit exceeded

解决方案：

• 降低请求频率
• 实现自己的速率限制策略
• 联系 API 管理员申请提高速率限制

无效 URL 错误

错误：Invalid URL format

解决方案：

• 确保 URL 包含协议（http:// 或 https://）
• 检查域名是否有拼写错误
• 确认 URL 可在普通浏览器中访问

关于爬取功能的说明

出于以下原因，已从此 MCP 服务中有意移除爬取功能：

1. 上下文管理：爬取功能会在 MCP 服务的上下文中提供过多信息，可能导致大模型的上下文溢出。这是因为爬取多个页面会生成大量文本，超出大多数模型的上下文限制。

2. 异步操作：爬取以异步方式运行，而 MCP 服务架构最适合采用同步请求-响应模式。爬取的异步特性使其难以集成到 MCP 的同步通信模型中。

3. 与文档保持一致：我们已使可用工具与主要文档保持一致，以确保内容一致且清晰易懂。

如果需要网站爬取功能，可以使用单个抓取工具处理多个目标 URL，或者在 MCP 服务之外实现自定义解决方案。

架构改进

代码库经过优化，包含多项重要改进：

1. 简化服务层

• 采用函数式方法，减少重复。
• 所有服务方法都使用一致的错误处理方式。
• 使用 Zod 模式进行严格的输入验证。
• 明确区分服务与工具的职责。

2. 增强错误处理

• 集中管理错误处理工具。
• 采用一致的错误格式，提升用户体验。
• 正确分类错误（验证、API、网络、超时）。
• 改进错误日志，加入上下文信息。
• 提供易于大模型理解的错误消息。

3. 改进类型安全

• 消除不安全的 any 类型。
• 添加适当的类型断言和验证。
• 统一返回类型，并正确设置错误标记。
• 使用 Zod 模式验证配置和工具输入。

4. 配置管理

• 稳健地处理环境变量并进行验证。
• 配置无效时回退到合理的默认值。
• 为配置问题提供清晰的错误消息。
• 集中管理配置的模块。

5. 代码组织

• 统一文件和模块结构。
• 使用工厂模式创建工具和响应。
• 简化 API 客户端的使用。
• 更好地区分职责。

开发

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run coverage

# Lint code
npm run lint

# Type check
npm run typecheck

测试

项目包含针对所有工具和服务的全面测试。运行测试：

npm test

生成测试覆盖率报告：

npm run coverage

测试套件包括：

• 所有 MCP 工具的单元测试。
• 错误处理测试。
• 参数验证测试。
• 输入验证测试。

贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 此仓库。
2. 创建功能分支（git checkout -b feature/amazing-feature）。
3. 提交更改（git commit -m 'Add some amazing feature'）。
4. 将分支推送到仓库（git push origin feature/amazing-feature）。
5. 创建 Pull Request。

许可证

本项目采用 MIT 许可证。