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

Related MCP server: WebSearch

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

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

Monitor Tools

Research Tools

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