# Reported issues for Firecrawl MCP Server

Pod holds 24 of 91 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [Firecrawl MCP Server](/mcp/firecrawl-mcp-server).

## Most discussed

### Server crashes with "Server does not support completions" error on startup

## Description
  The firecrawl-mcp server fails to start with an error about unsupported completions capability, preventing it from connecting as an
  MCP server in Claude Code/Claude Desktop.

  ## Environment
  - **Package**: `firecrawl-mcp` (installed via `npx -y firecrawl-mcp`)
  - **Node version**: v25.2.0
  - **Platform**: macOS (Darwin 25.1.0)
  - **MCP Client**: Claude Code CLI
  - **Installation method**: npx

  ## Steps to Reproduce
  1. Configure MCP server:
     ```bash
     claude m

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/133) · 2025-11-14 · open · external user · 13 comments

### Using local self-hosted Firecrawl instance is broken since v2.0.0

So far I was using the MCP server with a local self-hosted Firecrawl instance (Docker) and it worked fine.

Today I’ve noticed that the client now suddenly demands the FIRECRAWL_API_KEY to be set. That shouldn’t be necessary when FIRECRAWL_API_URL is set.

When setting a fake API Key, the MCP server only returns 404 errors. I suppose that is because the self-hosted instance isn’t used at all as soon as an API key is set. It seems to entirely ignore FIRECRAWL_API_URL in that case.

Can someone co

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/93) · 2025-08-25 · closed · external user · 8 comments

### Client Closed or Failed to create on Windows 11

![Image](https://github.com/user-attachments/assets/1f5c4e56-16ab-4f45-8bda-9e8b293cc962)

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/36) · 2025-04-05 · open · external user · 6 comments

### Not working on Cursor 0.47.8

The latest version of cursor no longer has the add MCP dialogue box. Instead it takes you directly to `mcp.json`.

Adding this to the json, substituting my API key adds the MCP server to the MCP server list in cursor settings, but the firecrawl MCP server will not initialize properly.

```
{
  "mcpServers": {
    "firecrawl-mcp-server": {
      "command": "env FIRECRAWL_API_KEY=my-api-key npx",
      "args": ["-y", "firecrawl-mcp"]
    }
  }
}
```

I see this in the list (edited to remove my api

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/28) · 2025-03-22 · closed · external user · 9 comments

### MCP Integration Issue: "Cannot read properties of undefined (reading 'status')" Error When Calling firecrawl-mcp Tool from Cursor

MCP Integration Issue: "Cannot read properties of undefined (reading 'status')" Error When Calling firecrawl-mcp Tool from Cursor

Description
Environment Information
Operating System: Windows
Local firecrawl version: v1.6.0
firecrawl-mcp version: 1.5.0
Cursor version: 0.47.5

Problem Description
I have successfully deployed firecrawl service locally using Docker Compose, and the API works normally when tested with curl. However, when I try to call firecrawl tools through Cursor's MCP service, I

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/20) · 2025-03-15 · open · external user · 6 comments

### Running cursor on windows but working with wsl

Please write a guide about how to configure this when running cursor on windows 11 and using WSL distro on it.

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/18) · 2025-02-28 · open · external user · 19 comments

### Initialization problem on custom client

Hi, I'm working on custom client and using with stdio.

`            server_params = StdioServerParameters(
                command=self.server_config.command,
                args=self.server_config.args,
                env=self.server_config.env,
            )

            stdio_transport = await self.exit_stack.enter_async_context(
                stdio_client(server_params)
            )
            self.stdio, self.write = stdio_transport
            session = await self.exit_stack.enter_a

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/17) · 2025-02-27 · closed · external user · 9 comments

### No Tools Found

Confirm , Command is: `env FIRECRAWL_API_KEY=fc-blah-blah-blah-my-api-key npx -y firecrawl-mcp` in total 

Where do i find the logs?

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/15) · 2025-02-21 · closed · external user · 10 comments

## Most recent

### firecrawl_search.limit has been unconstrained since the search tool was introduced

## Describe the Bug

The `firecrawl_search` MCP tool advertises `limit` as an unconstrained JSON
`number`, but the Search API accepts only an integer from 1 through 100. MCP
clients therefore accept values that the runtime rejects downstream.

I found this while testing Firecrawl's MCP surface with an internal agent
compatibility system at Bottomless. The reproduction is model-free and
read-only.

## To Reproduce

The current `tools/list` schema contains:

```json
{"limit":{"type":"number"}}
```

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/376) · 2026-08-19 · open · external user · 0 comments

### firecrawl_scrape: published inputSchema declares jsonOptions.schema as an object that admits no keys, breaking JSON extraction for schema-validating MCP clients

## Summary

The `inputSchema` that `firecrawl-mcp` publishes via `tools/list` declares
`firecrawl_scrape`'s `jsonOptions.schema` field as:

```json
{
  "type": "object",
  "propertyNames": { "type": "string" },
  "additionalProperties": false
}
```

There is no `properties` declaration, so under JSON Schema semantics this
accepts **only the empty object**. But this field is where callers pass an
arbitrary JSON Schema describing the extraction output — any legitimate value
necessarily contains ke

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/373) · 2026-08-18 · open · external user · 0 comments

### Feature Suggestion: Optional token metering & paid API key support via `neuforge-pay`

Hi @firecrawl,

Love the work on `firecrawl/firecrawl-mcp-server`! As usage grows across AI agent frameworks, server compute costs can start adding up quickly. We've also seen developers report that their autonomous agents accidentally burn through thousands of dollars in a single session because traditional payment rails lack built-in agent guardrails.

Would you be open to adding an optional usage metering & billing decorator using `neuforge-pay`? It acts as a proactive **Spend Firewall** and 

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/370) · 2026-08-13 · open · external user · 0 comments

### README: keyless tool list and `formats` object syntax both disagree with v3.23.3 behavior

Two spots in `README.md` on `main` describe behavior that the current code does not implement. Both were hit while setting up the hosted endpoint, and both cost some debugging time, so filing them together.

Verified against `https://mcp.firecrawl.dev/v2/mcp` on 2026-08-06, which reports `serverInfo: {"name":"firecrawl-fastmcp","version":"3.23.3"}` — the same version as `package.json` on `main`, so this is not a stale deployment.

---

### 1. Keyless tool list says `interact`, but the endpoint s

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/357) · 2026-08-06 · open · external user · 0 comments

### Gemini Spark custom connected apps: OAuth Dynamic Client Registration fails — flow asks for static Client ID/Secret

**Describe the bug**

Connecting the hosted Firecrawl MCP server as a *custom connected app* inside **Gemini Spark** (gemini.google.com → Settings & help → Connected Apps → "Custom apps for Spark" → Add a custom app) fails with:

> "Automatic registration with this server failed. Please enter the OAuth client ID and client secret to complete the connection."

Gemini's OAuth client attempts Dynamic Client Registration against Firecrawl's advertised `registration_endpoint`, the registration fails,

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/345) · 2026-08-02 · closed · external user · 2 comments

### firecrawl_research_search_papers returns 404 when using self-hosted Firecrawl

I'm using a self-hosted Firecrawl service, and most MCP search tools are working as expected. However, the firecrawl_research_search_papers tool consistently fails.

**The error I receive is:**

Tool 'firecrawl_research_search_papers' execution failed:

Request failed with status code 404

**Environment**

Firecrawl: Self-hosted
MCP Server  : 
```
command: "npx"
    args:
      - "-y"
      - "firecrawl-mcp"
```

**Expected Behavior**

The firecrawl_research_search_papers tool should execute suc

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/341) · 2026-07-29 · open · external user · 0 comments

### `firecrawl-build` marks `FIRECRAWL_API_KEY` as required, but keyless execution is allowed

Hi team - I was using Firecrawl through Codex.

The firecrawl-build skill declares:
inputs:
  - name: FIRECRAWL_API_KEY
  - ...
    **required: true**

Based on that, the agent-generated script initially treated the API key as mandatory and stopped when FIRECRAWL_API_KEY was not set.
But later, the agent removed its own hard requirement, retried the same v2 /scrape flow without the auth header, and the run succeeded through the available keyless path.
That created some confusion for implementati

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/327) · 2026-07-23 · open · external user · 1 comment

### The `firecrawl_feedback` returned 400 INVALID_BODY for search feedback

Hello,
I was using Firecrawl’s MCP through Codex and noticed that the agent attempted to submit feedback three times. All three calls failed with the same error.

### Tool call

```json
{
  "endpoint": "search",
  "jobId": "019f8a0a-a559-709b-b4b1-cb76efe17797",
  "rating": "bad",
  "issues": ["no_results"],
  "note": "No useful results for batch scrape pricing query."
}
```

### Response

```json
[
  {
    "type": "text",
    "text": "{\"success\":false,\"status\":400,\"feedbackErrorCode\":\"IN

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/326) · 2026-07-23 · open · external user · 0 comments

### 132 parameters have no description — likely hurting agent tool-selection accuracy

Hi! I maintain [mcpgrade](https://github.com/TengByte/mcpgrade), an open-source scorecard
for MCP server agent-usability, and recently benchmarked 36 popular servers
([results](https://tengli.dev/posts/mcp-servers-failing-agents.html)). I re-verified against
firecrawl-mcp 3.22.4 today before filing this.

The headline: **132 of your parameters ship with no description** — `url`, `formats`,
`jsonOptions`, `queryOptions` on `firecrawl_scrape`, and so on across the catalog. The model
gets a name an

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/325) · 2026-07-22 · open · external user · 0 comments

### firecrawl_search declares readOnlyHint: true but accepts scrapeOptions.actions (click/write/executeJavascript)

Hello, I maintain [actlint](https://github.com/formael/actlint), a static linter that checks MCP tool annotations against what their input schemas allow.

### The observation

On `firecrawl-mcp@3.22.3`, `firecrawl_search` declares `readOnlyHint: true`, but its input schema includes `scrapeOptions.actions` with action types `click`, `write`, `press`, and `executeJavascript`. As declared, the tool can fill and submit forms and run arbitrary JS on the pages it visits, while carrying the hint that l

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/311) · 2026-07-12 · open · external user · 0 comments

### Tool descriptions embed usage essays (~18k tokens of definitions per session) while 24/26 tools have undescribed parameters

The server's 26 tool definitions cost **~18,511 tokens** (tiktoken cl100k) at `tools/list` — paid by every session up front. The bulk is long-form description sections (`firecrawl_scrape` ~1201 tokens of description; "Usage Example", "CRITICAL - Format Selection", "Common mistakes"...). That's documentation, and models are good at *reading docs on demand* — but it's being paid per-session as selection metadata. At the same time, 24 of 26 tools declare parameters with **no** `description`, so the

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/309) · 2026-07-10 · open · external user · 0 comments

### Arbitrary local file read via firecrawl_parse (no path confinement) in firecrawl-mcp

reported via email on 5 June 2026 - no response:

The firecrawl_parse tool takes filePath as z.string().min(1) with no confinement and reads it directly: path.resolve(filePath) then readFile(absPath) (src/index.ts ~L1722), uploading the bytes to ${FIRECRAWL_API_URL}/v2/parse and returning the parsed content to the caller. No base-directory check, no rejection of absolute paths or ../. The tool is registered in the standard self-hosted config (CLOUD_SERVICE != 'true', FIRECRAWL_API_URL set).

```

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/306) · 2026-07-08 · open · external user · 0 comments

### firecrawl local network error cannot accept

trying using firecrawl mcp for local network server.
self hosted firecrawl installed in my NAS and access by local network 
setting FIRECRAWL_API_URL to http://192.x.x.x:3002 (port used to 3000 change to 3002)
and it error reject by installer

using npx to install

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_URL="http://192.x.x.x:3002" npx -y firecrawl-mcp

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/284) · 2026-06-22 · open · external user · 0 comments

### MCP tool descriptions teach models the wrong calling convention, causing systematic tool-call failures

Some models using Firecrawl MCP call the tools using incorrect format e.g.

```
'arguments': '{"name":"firecrawl_search","arguments":{"query":"My search query", "limit":5}}'
```

which causes an error:

```
"MCP error -32602: Tool 'firecrawl_search' parameter validation failed: query: Invalid input: expected string, received undefined.
```

A correct way to call the tool is to use flat arguments, matching `input_schema` directly.

```
'arguments': '{"query":"My search query", "limit":5}'
```

Up

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/279) · 2026-06-16 · open · external user · 0 comments

### CLI metadata flags require FIRECRAWL_API_KEY instead of printing help/version

## Summary

The published `firecrawl-mcp@3.20.2` CLI validates Firecrawl configuration before handling top-level metadata flags. With `FIRECRAWL_API_KEY` and `FIRECRAWL_API_URL` unset, `firecrawl-mcp --help`, `firecrawl-mcp --version`, and an unknown flag all fail with the same runtime configuration error.

This makes it impossible to inspect usage or the installed package version without already having Firecrawl credentials configured.

## Reproduction

On Windows PowerShell:

```powershell
mkd

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/256) · 2026-06-08 · open · external user · 0 comments

### stdio: every tool call returns "Unauthorized" in 3.18.0+ with FIRECRAWL_API_KEY (regression from 3.17.0)

## Summary

Since the 3.18.0 → 3.19.1 burst released on 2026-05-28 (~02:09–02:19 UTC), every tool call over the **stdio** transport fails with:

```
Tool 'firecrawl_search' execution failed: Unauthorized: API key is required when not using a self-hosted instance
```

…even when `FIRECRAWL_API_KEY` is properly set in the env block, which is the exact configuration documented in the README for stdio. 3.17.0 (the previous npm `latest`, published 2026-05-17) works with the same env and the same comm

[Read the thread](https://github.com/firecrawl/firecrawl-mcp-server/issues/246) · 2026-05-28 · closed · external user · 4 comments

The remaining reports are on [the project's issue tracker](https://github.com/firecrawl/firecrawl-mcp-server.git/issues).