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.

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

Configure MCP server:
```
claude m
```

Read the thread · 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 · 2025-08-25 · closed · external user · 8 comments

Client Closed or Failed to create on Windows 11

Read the thread · 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 · 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

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 · 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 · 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 · 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 · 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:

{"limit":{"type":"number"}}

Read the thread · 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:

{
  "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 · 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 · 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 · 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 · 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 · 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 · 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

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

Response

[
  {
    "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 · 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 · 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}'

Read the thread · 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:

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).

Reported issues for Firecrawl MCP Server

Most discussed

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

Description

Environment

Steps to Reproduce

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

Client Closed or Failed to create on Windows 11

Not working on Cursor 0.47.8

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

Running cursor on windows but working with wsl

Initialization problem on custom client

No Tools Found

Most recent

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

Describe the Bug

To Reproduce

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

Summary

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

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

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

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

firecrawl_research_search_papers returns 404 when using self-hosted Firecrawl

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

The firecrawl_feedback returned 400 INVALID_BODY for search feedback

Tool call

Response

firecrawl local network error cannot accept

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

CLI metadata flags require FIRECRAWL_API_KEY instead of printing help/version

Summary

Reproduction

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

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

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

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

The `firecrawl_feedback` returned 400 INVALID_BODY for search feedback