Firecrawl Simple MCP 服务器

一个用于 Firecrawl Simple 的模型上下文协议 (MCP) 服务器。Firecrawl Simple 是一个强大的网络爬虫和站点地图工具，使大型语言模型 (LLM) 能够访问和处理网络内容。

项目链接

• GitHub 仓库
• npm 包

目录

• 前提条件
• 快速开始
• 特性
• 安装
• 使用
• 配置
• 可用工具
• 问题排查
• 关于爬取功能的说明
• 架构改进
• 开发
• 测试
• 贡献
• 许可证

前提条件

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

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

快速开始

# 安装包
npm install -g firecrawl-simple-mcp

# 使用默认配置运行
FIRECRAWL_API_URL=http://localhost:3002/v1 firecrawl-simple-mcp

# 使用简单的抓取请求进行测试
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

使用

运行服务器

# 使用自托管的 Firecrawl Simple 的基本用法
FIRECRAWL_API_URL=http://localhost:3002/v1 firecrawl-simple-mcp

# 使用其他配置
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. 输入以下内容：
   • Name: "firecrawl-simple-mcp" (或您喜欢的名称)
   • Type: "command"
   • 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 服务器的上下文中提供了过多的信息，这可能导致 LLM 的上下文溢出问题。这是因为爬取多个页面会生成大量文本，这些文本将超过大多数模型的上下文限制。

2. 异步操作: 爬取以异步方式运行，这对于最适合同步请求-响应模式的 MCP 服务器架构来说并不理想。爬取的异步性质使其难以与 MCP 的同步通信模型集成。

3. 文档对齐: 我们已将可用工具与主要文档对齐，以确保用户的一致性和清晰度。

如果您需要网站爬取功能，请考虑使用具有多个目标 URL 的单个抓取工具，或在 MCP 服务器外部实施自定义解决方案。

架构改进

代码库已通过以下几项关键改进进行了优化：

1. 简化服务层

• 采用函数式方法，减少重复。
• 所有服务方法中一致的错误处理。
• 使用 Zod 模式进行强输入验证。
• 服务和工具之间清晰的关注点分离。

2. 增强的错误处理

• 集中式错误处理实用程序。
• 一致的错误格式，以获得更好的用户体验。
• 正确的错误分类（验证、API、网络、超时）。
• 改进的错误日志记录，包含上下文信息。
• 适用于 LLM 使用的用户友好型错误消息。

3. 类型安全改进

• 消除不安全的 any 类型。
• 添加了正确的类型断言和验证。
• 具有正确错误标志的一致返回类型。
• 用于配置和工具输入的 Zod 模式验证。

4. 配置管理

• 通过验证进行强大的环境变量处理。
• 当配置无效时，回退到合理的默认值。
• 针对配置问题的清晰错误消息。
• 集中式配置模块。

5. 代码组织

• 一致的文件和模块结构。
• 用于创建工具和响应的工厂模式。
• 简化的 API 客户端使用。
• 更好的关注点分离。

开发

# 安装依赖
npm install

# 在开发模式下运行
npm run dev

# 构建
npm run build

# 运行测试
npm test

# 运行带有覆盖率的测试
npm run coverage

# 检查代码风格
npm run lint

# 类型检查
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 许可证的许可。