mekayelanik/firecrawl-mcp repository overview

⁠Firecrawl MCP Server

⁠Multi-Architecture Docker Image for Web Scraping & Crawling

⁠📋 Table of Contents

• Overview⁠
• Supported Architectures⁠
• Available Tags⁠
• Quick Start⁠
• Configuration⁠
• MCP Client Configuration⁠
• Network Configuration⁠
• Updating⁠
• Troubleshooting⁠
• Additional Resources⁠
• Support & License⁠
• Major Changes⁠

⁠😎 Buy Me a Coffee ☕︎

Your support encourages me to keep creating/supporting my open-source projects. If you found value in this project, you can buy me a coffee to keep me inspired.

⁠

⁠Overview

Firecrawl MCP Server provides web scraping and crawling capabilities through the Model Context Protocol via the Firecrawl API. Built on Alpine Linux for minimal footprint and maximum security.

⁠Key Features

✨ Multi-Architecture Support - Native support for x86-64 and ARM64
🚀 Multiple Transport Protocols - StreamableHTTP and SSE via mcp-proxy
🔒 Secure by Design - Alpine-based with minimal attack surface
⚡ High Performance - ZSTD compression for faster deployments
🎯 Production Ready - Stable releases with comprehensive testing
🔧 Easy Configuration - Simple environment variable setup

⁠Supported Architectures

⁠Available Tags

⁠System Requirements

• Docker Engine: 23.0+
• RAM: Minimum 512MB
• CPU: Single core sufficient

⁠Quick Start

⁠Docker Compose (Recommended)

services:
  firecrawl-mcp:
    image: 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
      # Optional: require Bearer token auth at HAProxy layer
      # - API_KEY=replace-with-strong-secret
    hostname: firecrawl-mcp
    domainname: local

Deploy:

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

⁠Docker CLI

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 \
  mekayelanik/firecrawl-mcp:stable

⁠Access Endpoints

When HTTPS is enabled (ENABLE_HTTPS=true), use TLS endpoints:

⁠Configuration

⁠Environment Variables

⁠HTTPS and HTTP Version Notes

• If ENABLE_HTTPS=true and cert files are missing, the container auto-generates a self-signed certificate.
• If TLS_CERT_PATH and TLS_KEY_PATH exist, they are merged into TLS_PEM_PATH and used directly.
• HTTP_VERSION_MODE=h3 (or auto) enables HTTP/3 only when HAProxy build includes QUIC; otherwise it safely falls back.

⁠API Key Authentication Notes

• Set API_KEY to enforce authentication at reverse proxy level.
• Expected header format: Authorization: Bearer <API_KEY>.
• Localhost health checks remain accessible for liveness/readiness.

⁠Rate Limiting and IP Access Control

• Rate limiting: Set RATE_LIMIT=100 to allow 100 requests per RATE_LIMIT_PERIOD (default 10s) per IP. Exceeding the limit returns HTTP 429 with a Retry-After header.
• Connection limiting: Set MAX_CONNECTIONS_PER_IP=50 to cap concurrent connections per IP. Exceeding returns HTTP 429.
• IP blocklist: Set IP_BLOCKLIST=192.0.2.0/24,198.51.100.5 to block specific IPs/CIDRs. Blocked IPs receive HTTP 403.
• IP allowlist: Set IP_ALLOWLIST=10.0.0.0/8,192.168.1.0/24 to allow only listed IPs/CIDRs. All others receive HTTP 403. Localhost is always allowed.
• All features default to disabled. Combine as needed — blocklist is checked before allowlist.

⁠User & Group IDs

Find your IDs and set them to avoid permission issues:

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

⁠Timezone Examples

- TZ=Asia/Dhaka        # Bangladesh
- TZ=America/New_York  # US Eastern
- TZ=Europe/London     # UK
- TZ=UTC               # Universal Time

⁠Memory & Concurrency Tuning

This image embeds mcp-proxy (sparfenyuk/mcp-proxy) as the stdio↔HTTP bridge. Key knobs:

• MCP_PROXY_STATELESS=false (default): one stdio backend child is shared across all MCP sessions, JSON-RPC-id-multiplexed. Minimal memory, no per-request fork cost.
• MCP_PROXY_STATELESS=true: per-request transport instance. Use only when full session isolation is required — memory grows with concurrency.
• HAPROXY_FRONTEND_MAXCONN / HAPROXY_SERVER_MAXCONN: HAProxy-level caps. Bound bursts so the backend cannot be flooded. Defaults of 64/16 are sensible for a single replica.

⁠MCP Client Configuration

⁠Transport Support

⁠VS Code (Cline/Roo-Cline)

Configure in .vscode/settings.json:

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

⁠Claude Desktop App/Claude Code

Configuration:

⁠With API_KEY

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

⁠Without API_KEY

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

⁠Codex CLI

Configure in ~/.codex/config.json:

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

⁠Codeium (Windsurf)

Configure in .codeium/mcp_settings.json:

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

⁠Cursor

Configure in ~/.cursor/mcp.json:

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

⁠Testing Configuration

Verify with MCP Inspector⁠:

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

⁠Network Configuration

⁠Comparison

⁠Bridge Network (Default)

services:
  firecrawl-mcp:
    image: mekayelanik/firecrawl-mcp:stable
    ports:
      - "8016:8016"

Benefits: Container isolation, easy setup, works everywhere Access: http://localhost:8016/mcp

⁠Host Network (Linux Only)

services:
  firecrawl-mcp:
    image: mekayelanik/firecrawl-mcp:stable
    network_mode: host

Benefits: Maximum performance, no NAT overhead, no port mapping needed Considerations: Linux only, shares host network namespace Access: http://localhost:8016/mcp

⁠MACVLAN Network (Advanced)

services:
  firecrawl-mcp:
    image: 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

Benefits: Dedicated IP, direct LAN access Considerations: Linux only, requires additional setup Access: http://192.168.1.100:8016/mcp

⁠Updating

⁠Docker Compose

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

⁠Docker CLI

docker pull mekayelanik/firecrawl-mcp:stable
docker stop firecrawl-mcp && docker rm firecrawl-mcp
# Run your original docker run command
docker image prune -f

⁠One-Time Update with Watchtower

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

⁠Troubleshooting

⁠Pre-Flight Checklist

• ✅ Docker Engine 23.0+
• ✅ Port 8016 available
• ✅ Sufficient startup time (ARM devices)
• ✅ Latest stable image
• ✅ Correct configuration

⁠Common Issues

⁠Container Won't Start

# Check Docker version
docker --version

# Verify port availability
sudo netstat -tulpn | grep 8016

# Check logs
docker logs firecrawl-mcp

⁠Permission Errors

# Get your IDs
id $USER

# Update configuration with correct PUID/PGID
# Fix volume permissions if needed
sudo chown -R 1000:1000 /path/to/volume

⁠Client Cannot Connect

# Test connectivity
curl http://localhost:8016/mcp
curl http://host-ip:8016/mcp
curl -k https://localhost:8016/mcp
curl -k https://host-ip:8016/mcp

# Check firewall
sudo ufw status

# Verify container
docker inspect firecrawl-mcp | grep IPAddress

⁠Slow ARM Performance

• Wait 30-60 seconds after start
• Monitor: docker logs -f firecrawl-mcp
• Check resources: docker stats firecrawl-mcp
• Use faster storage (SSD vs SD card)

⁠Debug Information

When reporting issues, include:

# System info
docker --version && uname -a

# Container logs
docker logs firecrawl-mcp --tail 200 > logs.txt

# Container config
docker inspect firecrawl-mcp > inspect.json

⁠Additional Resources

⁠Documentation

• 📚 Firecrawl Official Docs⁠
• 📦 NPM Package⁠
• 🔧 MCP Inspector⁠

⁠Docker Resources

• 🐳 Docker Compose Best Practices⁠
• 🌐 Docker Networking⁠
• 🛡️ Docker Security⁠

⁠Monitoring

• 📊 Diun - Update Notifier⁠
• ⚡ Watchtower⁠

⁠😎 Buy Me a Coffee ☕︎

Your support encourages me to keep creating/supporting my open-source projects. If you found value in this project, you can buy me a coffee to keep me inspired.

⁠

⁠Support & License

⁠Getting Help

Docker Image Issues:

• GitHub: firecrawl-mcp-docker/issues⁠

Firecrawl MCP Issues:

• GitHub: nicholasgriffintn/firecrawl-mcp/issues⁠
• Website: firecrawl.dev⁠

⁠Contributing

We welcome contributions:

1. Report bugs via GitHub Issues
2. Suggest features
3. Improve documentation
4. Test beta releases

⁠License

GPL License. See LICENSE⁠ for details.

Firecrawl MCP server has its own license - see Main NPM repo⁠.

⁠Major Changes

• Initial Release: Full CI/CD pipeline with HAProxy, HTTPS/TLS, QUIC/HTTP3, API key auth