Firecrawl Multiple Keys

A Firecrawl MCP server with built-in support for multiple API keys. It exposes Firecrawl's web search, scraping, crawling, extraction, browser interaction, monitoring, and research tools to OpenCode and other MCP clients.

This fork is useful when you want one local Firecrawl MCP server that rotates across a pool of API keys instead of configuring several separate MCP server entries.

Highlights

• Local stdio MCP server by default
• Optional Streamable HTTP transport for hosted or local HTTP usage
• Multi-key rotation with FIRECRAWL_API_KEYS
• Single-key fallback with FIRECRAWL_API_KEY
• Process-local round-robin key selection
• Retry/failover across pooled keys for retryable Firecrawl errors where safe
• Firecrawl cloud and self-hosted API support
• TypeScript source bundled with tsup

Requirements

• Node.js 22 or newer
• pnpm
• One or more Firecrawl API keys
• OpenCode or another MCP-compatible client

Install

git clone https://github.com/AdvaitR7/firecrawl-mcp-multiple-keys.git
cd firecrawl-mcp-multiple-keys
pnpm install
pnpm run build

The build creates dist/index.js. MCP clients should run that file with Node.

Configure API Keys

For multiple keys, set FIRECRAWL_API_KEYS as a comma-separated or whitespace-separated list:

FIRECRAWL_API_KEYS=firecrawl_key_1,firecrawl_key_2

For a single key, set FIRECRAWL_API_KEY:

FIRECRAWL_API_KEY=firecrawl_key_1

FIRECRAWL_API_KEYS takes precedence over FIRECRAWL_API_KEY unless FIRECRAWL_OAUTH_TOKEN is set.

Key Rotation Behavior

At startup, the server loads FIRECRAWL_API_KEYS into a process-local key pool. Each request that uses the pool starts with the next key in sequence.

request 1 -> key 1
request 2 -> key 2
request 3 -> key 1
request 4 -> key 2

For retryable failures such as 429, 5xx, timeout, or network errors, supported read-style operations can try remaining keys in the current cycle. Mutating operations are more conservative to avoid duplicate jobs.

Header credentials and FIRECRAWL_OAUTH_TOKEN bypass the environment key pool.

OpenCode Setup

Build the project first:

pnpm install
pnpm run build

Add a local MCP entry to your OpenCode config. Use an absolute path to dist/index.js.

Multi-key configuration:

{
  "mcp": {
    "firecrawl": {
      "type": "local",
      "command": ["node", "/absolute/path/to/firecrawl-mcp-multiple-keys/dist/index.js"],
      "enabled": true,
      "timeout": 30000,
      "environment": {
        "FIRECRAWL_API_KEYS": "firecrawl_key_1,firecrawl_key_2"
      }
    }
  }
}

Single-key configuration:

{
  "mcp": {
    "firecrawl": {
      "type": "local",
      "command": ["node", "/absolute/path/to/firecrawl-mcp-multiple-keys/dist/index.js"],
      "enabled": true,
      "timeout": 30000,
      "environment": {
        "FIRECRAWL_API_KEY": "firecrawl_key_1"
      }
    }
  }
}

Restart OpenCode after changing MCP configuration.

Environment Variables

Variable	Required	Description
FIRECRAWL_API_KEYS	No	Comma- or whitespace-separated API keys for round-robin rotation
FIRECRAWL_API_KEY	No	Single Firecrawl API key fallback
FIRECRAWL_OAUTH_TOKEN	No	Static Firecrawl OAuth access token for stdio usage
FIRECRAWL_API_URL	No	Custom Firecrawl API URL for self-hosted instances
HTTP_STREAMABLE_SERVER	No	Set to true to use Streamable HTTP transport
SSE_LOCAL	No	Set to true to use local HTTP stream behavior
CLOUD_SERVICE	No	Set to true for hosted cloud-service behavior
PORT	No	HTTP transport port, default 3000
HOST	No	HTTP transport host, default localhost outside cloud mode

Transport Modes

By default, the server starts on stdio:

FIRECRAWL_API_KEYS=firecrawl_key_1,firecrawl_key_2 node dist/index.js

For local Streamable HTTP transport:

HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=firecrawl_key_1 node dist/index.js

Direct terminal execution of the stdio server will wait for MCP protocol input. For normal usage, run it through OpenCode or another MCP client.

Tools

Core Firecrawl Tools

Tool	Description
firecrawl_scrape	Scrape a single URL with markdown, JSON, HTML, screenshots, or other formats
firecrawl_map	Discover URLs on a website
firecrawl_search	Search the web, news, images, GitHub, research, or PDFs
firecrawl_search_feedback	Send feedback for a previous Firecrawl search result
firecrawl_feedback	Send generic endpoint feedback for scrape, parse, map, or search jobs
firecrawl_crawl	Crawl multiple pages from a site or section
firecrawl_check_crawl_status	Check an existing crawl job status
firecrawl_extract	Extract structured data from one or more URLs
firecrawl_agent	Start an autonomous web research agent job
firecrawl_agent_status	Poll an agent job until completion
firecrawl_interact	Interact with a web page in a browser session
firecrawl_interact_stop	Stop an interaction session
firecrawl_parse	Parse uploaded or local documents, including PDFs

Monitor Tools

Tool	Description
firecrawl_monitor_create	Create a recurring monitor for pages or searches
firecrawl_monitor_list	List monitors
firecrawl_monitor_get	Get one monitor by ID
firecrawl_monitor_update	Update monitor settings
firecrawl_monitor_delete	Delete a monitor
firecrawl_monitor_run	Trigger a monitor check immediately
firecrawl_monitor_checks	List historical monitor checks
firecrawl_monitor_check	Inspect one monitor check and its page diffs

Research Tools

Tool	Description
firecrawl_research_search_papers	Search research papers by topic
firecrawl_research_inspect_paper	Fetch metadata for one paper
firecrawl_research_related_papers	Expand from seed papers through citation graph similarity
firecrawl_research_read_paper	Read relevant full-text passages for one paper
firecrawl_research_search_github	Search GitHub issues, pull requests, and readmes

Development

Install dependencies:

pnpm install

Build:

pnpm run build

Test:

pnpm test

Lint:

pnpm run lint

Format:

pnpm run format

Run the compiled stdio server:

FIRECRAWL_API_KEYS=firecrawl_key_1,firecrawl_key_2 pnpm start

Security

Never put real Firecrawl API keys in source files, README examples, screenshots, issues, or commits. Keep keys in your MCP client environment config, shell environment, or a local .env file that is not committed.

If a key is exposed, revoke it in Firecrawl and create a replacement key.

License

MIT