firecrawl / firecrawl/firecrawl-mcp-server

firecrawl_search MCP tool is missing documented /v2/search fields

Open
#219 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
7.5k
Forks
884
Avg merge
1d 11h
Merged PRs (30d)
14

Description

## Describe the Bug

The `firecrawl_search` MCP tool schema does not expose all documented public `/v2/search` request fields.

Checked against `firecrawl/firecrawl-mcp-server` `origin/main` at `400072e`.

Current `firecrawl_search` schema exposes:

```ts
{
query: string;
limit?: number;
tbs?: string;
filter?: string;
location?: string;
sources?: Array<{ type: "web" | "images" | "news" }>;
scrapeOptions?: ...;
enterprise?: Array<"default" | "anon" | "zdr">;
}
```

The public `/v2/search` API also documents:

```ts
{
categories?: Array<"github" | "research" | "pdf" | { type: "github" | "research" | "pdf" }>;
country?: string;
timeout?: number;
ignoreInvalidURLs?: boolean;
}
```

These fields are not currently available through the MCP tool schema.

## To Reproduce

1. Configure the Firecrawl MCP server.
2. Inspect the `firecrawl_search` tool schema.
3. Try to call `firecrawl_search` with documented `/v2/search` fields such as:

```json
{
"query": "machine learning",
"categories": ["research"],
"limit": 5
}
```

or:

```json
{
"query": "restaurants",
"country": "DE",
"location": "Germany",
"limit": 5
}
```

or:

```json
{
"query": "Firecrawl docs",
"timeout": 30000,
"ignoreInvalidURLs": true,
"limit": 5
}
```

4. These fields are not accepted by the current MCP tool schema.

## Expected Behavior

The MCP `firecrawl_search` tool should expose the documented `/v2/search` request fields.

Expected schema shape:

```ts
{
query: string;
limit?: number;
sources?: Array<
| "web"
| "images"
| "news"
| { type: "web" | "images" | "news" }
>;
categories?: Array<
| "github"
| "research"
| "pdf"
| { type: "github" | "research" | "pdf" }
>;
tbs?: string;
location?: string;
country?: string;
timeout?: number;
ignoreInvalidURLs?: boolean;
filter?: string;
enterprise?: Array<"default" | "anon" | "zdr">;
scrapeOptions?: ...;
}
```

The implementation should forward accepted MCP fields to `/v2/search`.

## Screenshots

Not applicable.

## Environment

- Repository: `firecrawl/firecrawl-mcp-server`
- Ref checked: `origin/main` at `400072e`
- Package version on main: `3.13.0`
- Published npm latest checked: `firecrawl-mcp@3.11.0`
- Node.js Version: Not version-specific; schema/source inspection. Local verification used Node v25.2.1.

## Logs

Not applicable.

## Additional Context

The current README Search example includes `country`:

```json
{
"name": "firecrawl_search",
"arguments": {
"query": "latest AI research papers 2023",
"limit": 5,
"country": "us",
"sources": [
{ "type": "web" },
{ "type": "images" },
{ "type": "news" }
]
}
}
```

But `country` is not present in the actual MCP tool schema.

The public `/v2/search` docs also document `categories`, `country`, `timeout`, and `ignoreInvalidURLs`.

The MCP implementation currently calls the Node SDK `client.search()`. The SDK currently does not forward `enterprise`, `country`, or expose the full Search response metadata.

Related SDK issues:

- https://github.com/firecrawl/firecrawl/issues/3437
- https://github.com/firecrawl/firecrawl/issues/3438

Contributor guide

No contributing guide indexed for this repository

Research direction

Start at the firecrawl_search tool schema and the implementation call to the Node SDK client.search(), then compare its accepted fields with the documented /v2/search request. Done means categories, country, timeout, and ignoreInvalidURLs are accepted by the MCP schema and forwarded to /v2/search; verify the README Search examples and tool schema.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, node.js
Domain
api
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.