Firecrawl MCP 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