mekayelanik/firecrawl-mcp

Firecrawl MCP Server

📋 目录

• 概述
• 支持的架构
• 可用标签
• 快速开始
• 配置
• MCP客户端配置
• 网络配置
• 更新
• 故障排除
• 其他资源
• 支持与许可
• 主要变更

概述

Firecrawl MCP Server通过Firecrawl API经由模型上下文协议（Model Context Protocol）提供Web抓取和爬取能力。基于Alpine Linux构建，具有最小的资源占用和最高的安全性。

核心功能

✨ 多架构支持 - 原生支持x86-64和ARM64
🚀 多种传输协议 - 支持HTTP、SSE和WebSocket
🔒 安全设计 - 基于Alpine，***面最小化
⚡ 高性能 - ZSTD压缩加速部署
🎯 生产就绪 - 稳定版本，经过全面测试
🔧 易于配置 - 简单的环境变量设置

支持的架构

💡 多架构镜像会自动为您的系统选择正确的架构。

可用标签

系统要求

• Docker引擎： 23.0+
• 内存： 至少512MB
• CPU： 单核即可

🔒 重要： 不要在没有适当安全措施（反向代理、SSL/TLS、身份验证、防火墙规则）的情况下将此容器直接暴露到互联网。

快速开始

Docker Compose（推荐）

yaml
services:
  firecrawl-mcp:
    image: docker.xuanyuan.run/mekayelanik/firecrawl-mcp:stable
    container_name: firecrawl-mcp
    restart: unless-stopped
    ports:
      - "8016:8016"
    environment:
      - PORT=8016
      - INTERNAL_PORT=38011
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Dhaka
      - NODE_ENV=production
      - PROTOCOL=HTTP
      - ENABLE_HTTPS=false
      - HTTP_VERSION_MODE=auto
      # 可选：在HAProxy层要求Bearer令牌认证
      # - API_KEY=replace-with-strong-secret
    hostname: firecrawl-mcp
    domainname: local

部署：

bash
docker compose up -d
docker compose logs -f firecrawl-mcp

Docker CLI

bash
docker run -d \
  --name=firecrawl-mcp \
  --restart=unless-stopped \
  -p 8016:8016 \
  -e PORT=8016 \
  -e INTERNAL_PORT=38011 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Asia/Dhaka \
  -e NODE_ENV=production \
  -e PROTOCOL=HTTP \
  -e ENABLE_HTTPS=false \
  -e HTTP_VERSION_MODE=auto \
  docker.xuanyuan.run/mekayelanik/firecrawl-mcp:stable

访问端点

启用HTTPS（ENABLE_HTTPS=true）时，使用TLS端点：

⚠️ 安全警告： 容器默认使用HTTP（ENABLE_HTTPS=false）以便本地设置。生产环境、公共网络或任何不受信任的环境中请使用ENABLE_HTTPS=true。

⏱️ ARM设备： 访问端点前请允许30-60秒的初始化时间。

配置

环境变量

HTTPS和HTTP版本说明

• 若ENABLE_HTTPS=true且证书文件缺失，容器会自动生成自签名证书。
• 若TLS_CERT_PATH和TLS_KEY_PATH存在，它们会合并到TLS_PEM_PATH并直接使用。
• HTTP_VERSION_MODE=h3（或auto）仅在HAProxy构建包含QUIC时启用HTTP/3，否则会安全回退。

API密钥认证说明

• 设置API_KEY以在反向代理层强制认证。
• 预期的请求头格式：Authorization: Bearer <API_KEY>。
• 本地健康检查始终可访问，用于存活/就绪检测。

速率限制和IP访问控制

• 速率限制： 设置RATE_LIMIT=100允许每IP在RATE_LIMIT_PERIOD（默认10s）内100个请求。超过限制返回HTTP 429及Retry-After头。
• 连接限制： 设置MAX_CONNECTIONS_PER_IP=50限制每IP并发连接数。超过返回HTTP 429。
• IP阻止列表： 设置IP_BLOCKLIST=192.0.2.0/24,198.51.100.5阻止特定IP/CIDR。被阻止IP返回HTTP 403。
• IP允许列表： 设置IP_ALLOWLIST=10.0.0.0/8,192.168.1.0/24仅允许列出的IP/CIDR。其他IP返回HTTP 403。本地主机始终允许。
• 所有功能默认禁用。可按需组合使用——阻止列表优先于允许列表检查。

用户和组ID

查找您的ID并设置以避免权限问题：

bash
id username
# uid=1000(user) gid=1000(group)

时区示例

yaml
- TZ=Asia/Dhaka        # 孟加拉国
- TZ=America/New_York  # 美国东部
- TZ=Europe/London     # 英国
- TZ=UTC               # 世界标准时间

MCP客户端配置

传输协议支持

⚠️ *WebSocket为实验性功能（https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1288%EF%BC%89

VS Code (Cline/Roo-Cline)

在.vscode/settings.json中配置：

json
{
  "mcp.servers": {
    "firecrawl": {
      "url": "http://host-ip:8016/mcp",
      "transport": "http"
    }
  }
}

Claude Desktop App/Claude Code

配置：

带API_KEY

claude mcp add-json github '{"type":"http","url":"http://localhost:8045/mcp","headers":{"Authorization":"Bearer <YOUR_API_KEY>"}}'

不带API_KEY

claude mcp add-json github '{"type":"http","url":"http://localhost:8045/mcp"}'

Codex CLI

在~/.codex/config.json中配置：

json
{
  "mcpServers": {
    "firecrawl": {
      "transport": "http",
      "url": "http://host-ip:8016/mcp"
    }
  }
}

Codeium (Windsurf)

在.codeium/mcp_settings.json中配置：

json
{
  "mcpServers": {
    "firecrawl": {
      "transport": "http",
      "url": "http://host-ip:8016/mcp"
    }
  }
}

Cursor

在~/.cursor/mcp.json中配置：

json
{
  "mcpServers": {
    "firecrawl": {
      "transport": "http",
      "url": "http://host-ip:8016/mcp"
    }
  }
}

配置测试

使用https://github.com/modelcontextprotocol/inspector%E9%AA%8C%E8%AF%81%EF%BC%9A

bash
npm install -g @modelcontextprotocol/inspector
mcp-inspector http://host-ip:8016/mcp

网络配置

比较

桥接网络（默认）

yaml
services:
  firecrawl-mcp:
    image: docker.xuanyuan.run/mekayelanik/firecrawl-mcp:stable
    ports:
      - "8016:8016"

优点： 容器隔离，易于设置，适用于所有环境
访问： http://localhost:8016/mcp

主机网络（仅Linux）

yaml
services:
  firecrawl-mcp:
    image: docker.xuanyuan.run/mekayelanik/firecrawl-mcp:stable
    network_mode: host

优点： 最高性能，无NAT开销，无需端口映射
注意事项： 仅Linux，共享主机网络命名空间
访问： http://localhost:8016/mcp

MACVLAN网络（高级）

yaml
services:
  firecrawl-mcp:
    image: docker.xuanyuan.run/mekayelanik/firecrawl-mcp:stable
    mac_address: "AB:BC:CD:DE:EF:01"
    networks:
      macvlan-net:
        ipv4_address: 192.168.1.100

networks:
  macvlan-net:
    driver: macvlan
    driver_opts:
      parent: eth0
    ipam:
      config:
        - subnet: 192.168.1.0/24
          gateway: 192.168.1.1

优点： 专用IP，直接LAN访问
注意事项： 仅Linux，需额外设置
访问： http://192.168.1.100:8016/mcp

更新

Docker Compose

bash
docker compose pull
docker compose up -d
docker image prune -f

Docker CLI

bash
docker pull docker.xuanyuan.run/mekayelanik/firecrawl-mcp:stable
docker stop firecrawl-mcp && docker rm firecrawl-mcp
# 运行您原始的docker run命令
docker image prune -f

使用Watchtower一键更新

bash
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  docker.xuanyuan.run/containrrr/watchtower \
  --run-once \
  firecrawl-mcp

故障排除

预检查清单

• ✅ Docker引擎23.0+
• ✅ 端口8016可用
• ✅ 足够的启动时间（ARM设备）
• ✅ 最新稳定镜像
• ✅ 正确的配置

常见问题

容器无法启动

bash
# 检查Docker版本
docker --version

# 验证端口可用性
sudo netstat -tulpn | grep 8016

# 查看日志
docker logs firecrawl-mcp

权限错误

bash
# 获取您的ID
id $USER

# 使用正确的PUID/PGID更新配置
# 必要时修复卷权限
sudo chown -R 1000:1000 /path/to/volume

客户端无法连接

bash
#