# 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

```bash
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:

```bash
FIRECRAWL_API_KEYS=firecrawl_key_1,firecrawl_key_2
```

For a single key, set `FIRECRAWL_API_KEY`:

```bash
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.

```text
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:

```bash
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:

```json
{
  "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:

```json
{
  "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:

```bash
FIRECRAWL_API_KEYS=firecrawl_key_1,firecrawl_key_2 node dist/index.js
```

For local Streamable HTTP transport:

```bash
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:

```bash
pnpm install
```

Build:

```bash
pnpm run build
```

Test:

```bash
pnpm test
```

Lint:

```bash
pnpm run lint
```

Format:

```bash
pnpm run format
```

Run the compiled stdio server:

```bash
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