MADPANDA Firecrawl MCP

<div align="center"> <h1>🐼 MADPANDA Firecrawl MCP</h1> <pre> ╔══════════════════════════════════════════════════════════╗ ║ M A D P A N D A // F I R E C R A W L ║ ║ BOUNDED WEB INTELLIGENCE OVER MCP ║ ╚══════════════════════════════════════════════════════════╝ </pre> <p>A security-first, bring-your-own-key MCP server for bounded Firecrawl<br> scraping, search, site mapping, credit visibility, and queue status.</p> <p> <a href="https://github.com/MADPANDA3D/FIRECRAWL-MCP/actions/workflows/ci.yml"><img alt="Verify" src="https://github.com/MADPANDA3D/FIRECRAWL-MCP/actions/workflows/ci.yml/badge.svg"></a> <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-ff2d55.svg"></a> <img alt="Node.js 22.22+ and 24.17+" src="https://img.shields.io/badge/node-22.22%2B%20%7C%2024.17%2B-339933?logo=nodedotjs&logoColor=white"> <img alt="MCP tools: 9" src="https://img.shields.io/badge/MCP%20tools-9-111827"> <img alt="Production dependencies: 0" src="https://img.shields.io/badge/runtime%20dependencies-0-22c55e"> </p> </div>

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.

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.

Mode	Use it when	Service access	Firecrawl credential
standalone	You are self-hosting this repository	Authorization: Bearer <MCP_ACCESS_TOKEN>	x-firecrawl-api-key per request
portal	The service is behind MAD MCP Portal	X-MADPANDA-PORTAL-GRANT matching MCP_PORTAL_GRANT_TOKEN	Portal forwards x-firecrawl-api-key per authorized user request

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.

Header	Standalone	Portal
Authorization: Bearer …	Required for every /mcp request	Not used
X-MADPANDA-PORTAL-GRANT	Not used	Required for every /mcp request
x-firecrawl-api-key	Required for provider tools	Required for provider tools
x-madpanda-user-id	Not used	Required for provider tools
x-firecrawl-max-operation-credits	Optional lower limit	Optional lower limit
x-firecrawl-daily-credit-limit	Optional lower limit	Optional lower limit

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

Tool	Provider route	Behavior
check_configuration	Local	Reports safe setup and limit metadata without values
list_capabilities	Local	Lists all nine tools and optional descriptors
get_endpoint_coverage	Local	Searches the 50-operation coverage ledger
get_tool_usage	Local	Returns one exact tool contract
firecrawl_get_credit_usage	GET /v2/team/credit-usage	Bounded, read-only team credit totals
firecrawl_get_queue_status	GET /v2/team/queue-status	Bounded, read-only queue and concurrency status
firecrawl_scrape_public_page	POST /v2/scrape	Paid, single public page, Markdown/main-content only
firecrawl_search_public_web	POST /v2/search	Paid, web metadata only, at most 10 results
firecrawl_map_public_site	POST /v2/map	Paid, at most 25 public links

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:

Variable	Required	Purpose
MCP_MODE	Yes	Startup access mode: standalone or portal
MCP_ACCESS_TOKEN	Standalone	Service access token; 32–4096 safe characters
MCP_PORTAL_GRANT_TOKEN	Portal	Portal-to-service grant; separate from provider credentials
MCP_HOST_PORT	No	Loopback host port for Compose; default 8080
FIRECRAWL_PROVIDER_EXECUTION_ENABLED	No	Enables provider tools; navigation remains local when false
FIRECRAWL_MAX_OPERATION_CREDITS	No	Projected per-call admission ceiling, 1–25
FIRECRAWL_DAILY_CREDIT_LIMIT	No	Projected daily admission ceiling, 1–50
FIRECRAWL_LEDGER_PATH	No	Hash-only preview/accounting ledger path
FIRECRAWL_REQUEST_TIMEOUT_MS	No	Provider timeout, capped at 30 seconds
FIRECRAWL_RESPONSE_MAX_BYTES	No	Provider response ceiling, capped at 1 MiB
MCP_REQUEST_BODY_MAX_BYTES	No	MCP request body ceiling
MCP_TOOL_OUTPUT_MAX_BYTES	No	Complete MCP tool-response ceiling, capped at 48 KiB

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

Symptom	Check
401 unauthorized	The access header must match the selected startup mode and configured service token
provider_execution_disabled	Set FIRECRAWL_PROVIDER_EXECUTION_ENABLED=true, then restart
setup_required	Supply x-firecrawl-api-key; Portal mode also requires x-madpanda-user-id
preview_mismatch or expired token	Repeat preview with the same arguments, headers, budgets, and current DNS
blocked_public_target	Use a public HTTP(S) hostname; private, local, literal-IP, or credential-bearing targets are rejected
Container unhealthy	Run docker compose logs --tail=100 firecrawl-mcp and confirm /health reports nine tools
Port 8080 is already in use	Set an unused MCP_HOST_PORT in .env, restart, and use that port in the client URL
Remote client cannot connect	Confirm TLS/proxy routing while leaving the application bound to loopback or a private container network

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.