MADPANDA Firecrawl MCP

What this server does

This project exposes nine carefully bounded MCP tools over HTTP:

• Four local navigation tools explain configuration, capabilities, endpoint coverage, and exact tool usage.

• Two read-only tools return whitelisted Firecrawl team credit and queue data.

• Three paid tools scrape one public page, search the public web, or map one public site through a preview-and-confirm flow.

It intentionally implements five Firecrawl v2 provider operations. All 50 operations in the reviewed v1 baseline are mapped in docs/endpoint-coverage.md: five are implemented and 45 are explicitly excluded. “Covered” means accounted for, not fully implemented.

The production runtime uses only Node.js built-ins. No Firecrawl key is stored by the service, and tests never contact Firecrawl.

Related MCP server: webcrawl-mcp

Choose an access mode

MCP_MODE is selected at startup. Changing it requires a restart; no MCP tool can change the mode while the server is running.

There is no unauthenticated “public mode.” Publishing the source does not make a deployed endpoint open to the internet.

Five-minute standalone deployment

You need Docker Engine with Compose, Git, Node.js 22.22+ or 24.17+ for the initializer, and a Firecrawl API key. The default Compose deployment builds the checked-out source and binds the server only to 127.0.0.1:8080.

git clone https://github.com/MADPANDA3D/FIRECRAWL-MCP.git
cd FIRECRAWL-MCP
node scripts/init-runtime-env.mjs
docker compose up -d --build
docker compose ps
curl --fail http://127.0.0.1:8080/health

The initializer creates an ignored .env with mode 0600, generates a strong standalone access token without printing it, and leaves real provider keys out of the file. Open .env locally to place the generated MCP_ACCESS_TOKEN into your MCP client's secret store. Do not commit or paste that token into issues, logs, screenshots, or shared configuration.

This standalone initializer enables provider execution because the endpoint is already bearer-authenticated. Portal deployments should begin with provider execution disabled until their broker, user-key storage, budgets, route, and immutable release identity have been admitted.

Expected health fields include:

{
  "status": "healthy",
  "service": "firecrawl-mcp",
  "tool_count": 9,
  "access_mode": "standalone"
}

/health reports readiness and release metadata, never credential values.

Connect an MCP client

Use the remote HTTP endpoint http://127.0.0.1:8080/mcp. Client configuration formats vary, but the logical shape is:

{
  "mcpServers": {
    "firecrawl": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_ACCESS_TOKEN}",
        "x-firecrawl-api-key": "${FIRECRAWL_API_KEY}"
      }
    }
  }
}

${...} above means “load this value from your client's secret or environment facility”; it is not guaranteed interpolation syntax for every client. Never commit the resolved values.

Navigation calls need only the service access header. Provider tools also need x-firecrawl-api-key. In portal mode, the broker additionally supplies a stable x-madpanda-user-id. Either mode may lower the server's projected credit-admission limits with the documented budget headers.

Paid-call confirmation

The three paid tools always require two calls:

1. Call the tool with its normal arguments. The service validates the request locally and returns a one-use preview token without contacting Firecrawl.

2. Repeat the exact arguments within 300 seconds with that previewToken and confirm: true.

Changing the arguments, credentials, deployment identity, local DNS answer set, or credit limits invalidates the preview. Paid calls receive one outbound attempt and are never retried automatically.

Credit limits gate the server's projected cost before a call; they cannot cap third-party billing after Firecrawl accepts it. If Firecrawl reports actual usage above the projection, the service records the actual charge, returns provider_credit_drift, and blocks later calls as the updated daily accounting requires. A single provider-pricing drift event can therefore exceed its local projection.

Tools

There are no tool aliases. Every descriptor includes bounded input and output schemas plus readOnlyHint, destructiveHint, openWorldHint, and idempotentHint where true.

Configuration

Start with .env.example. The principal settings are:

The Firecrawl API key deliberately has no supported server environment variable. Supply x-firecrawl-api-key through your MCP client's secret-backed HTTP headers; the service never persists or returns its value.

Production deployment

The default loopback binding is appropriate for a local client or a reverse proxy running on the same host. For remote access:

1. Keep the application behind TLS.

2. Preserve the Authorization header at the proxy.

3. Restrict direct access to port 8080; do not expose the container as an unauthenticated public service.

4. Store .env with mode 0600 and keep the ledger volume persistent.

5. Run exactly one server process or replica for a ledger. Do not share the file ledger between replicas or scale this runtime horizontally.

6. Apply reasonable connection and request-rate limits at the proxy.

7. Verify /health, authentication failure, tools/list, and one local navigation tool before enabling provider execution.

Portal deployment and broker headers are documented with placeholders in docs/portal-compat.md. Production operations and rollback are covered in docs/operator-runbook.md.

Release containers

Stable tags publish a scanned, provenance-attested linux/amd64 image to:

ghcr.io/madpanda3d/firecrawl-mcp-server

For a release deployment, set MCP_RUNTIME_IMAGE in .env to the immutable digest recorded in that GitHub Release, then run:

docker compose pull
docker compose up -d --no-build

Prefer @sha256:<digest> over a mutable tag for production and Portal use.

Security boundary

• The Firecrawl origin is fixed to https://api.firecrawl.dev:443.

• Only five exact method/path pairs may reach the provider.

• Public URL tools reject credentials, fragments, IP literals, unsafe ports, local/special-use names, private or mixed DNS answers, DNS changes between local preview and execution checks, and IPv6 transition/tunnel forms.

• Firecrawl resolves the submitted hostname independently; its provider-side SSRF and DNS protections remain part of the deployment trust boundary.

• Provider responses are capped at 1 MiB, whitelisted by tool, redacted, and capped again inside a complete 48 KiB MCP response.

• Provider HTML/raw-HTML fields, screenshots, base64 media, audio, video, headers, cookies, and unfiltered provider payloads are never returned.

• The ledger stores hashes and accounting state, not API keys, user IDs, URLs, arguments, or preview tokens.

• Ledger coordination is process-local. One-use previews and credit accounting require exactly one runtime process per ledger.

• Provider-derived content is marked untrusted_external_content=true and must never be treated as instructions.

The bounded scrape result contains provider-produced Markdown. That text may include markup and remains untrusted even after credential-pattern redaction.

Redaction is defense in depth, not a guarantee that arbitrary public pages contain no personal information. See docs/security-model.md and the security policy.

Run from source

Node.js 22.22+ or 24.17+ is supported.

npm ci --ignore-scripts
mkdir -p data
node scripts/init-runtime-env.mjs
node --env-file=.env src/server.js

For a source run, set FIRECRAWL_LEDGER_PATH=./data/firecrawl-ledger.json in .env. The application listens on the configured HOST and PORT; the default Compose mapping remains loopback-only at 127.0.0.1:8080.

Verification

npm ci --ignore-scripts
npm run check:conformance
npm audit --omit=dev
node scripts/init-runtime-env.mjs
docker compose config --quiet

The suite injects DNS and fetch implementations and makes no live Firecrawl requests.

Troubleshooting

Do not include access tokens, Firecrawl keys, request headers, or unredacted provider output in a support report.

Documentation

• Tool catalog

• Endpoint coverage

• Security model

• Deployment and operations

• Optional Portal integration

• Source and release provenance

• Contributing

• Support

License and trademark

The code is available under the MIT License. See NOTICE for clean-room and upstream-reference provenance.

Firecrawl is a trademark of its respective owner. This independent project is not an official Firecrawl product, distribution, or endorsement.