Skip to content
Back to search

firecrawl-mcp-server

🔥 Official Firecrawl MCP Server - Adds powerful web scraping and search to Cursor, Claude and any other LLM clients.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/firecrawl/firecrawl-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/firecrawl/firecrawl-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/firecrawl--firecrawl-mcp-server/badge.svg)](/listings/firecrawl--firecrawl-mcp-server)

HTML

<a href="/listings/firecrawl--firecrawl-mcp-server"><img src="/api/listings/firecrawl--firecrawl-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Hosted MCP (keyless free tier)

Connect to the remote hosted server with no setup:

https://mcp.firecrawl.dev/v2/mcp

On the keyless free tier, `scrape`, `search`, and `parse` work without an API key (rate-limited). Other tools such as `crawl`, `map`, and `agent` still need a key.

Prefer OAuth or an API key whenever the human can sign up. It unlocks the full tool set and higher limits.

For an interactive account connection, configure your MCP client to use this server URL. This is an MCP endpoint, **not a browser page**; use the client's account-connection flow and do not add a second Firecrawl server entry when reconnecting:

https://mcp.firecrawl.dev/v2/mcp-oauth

For an API-key connection (for example, an unattended integration), keep the server URL as:

https://mcp.firecrawl.dev/v2/mcp

Then configure the client's secure header or secret setting with:

Authorization: Bearer <FIRECRAWL_API_KEY>

Never put an API key in the server URL. Never put an API key in an agent chat. Configure it directly in the client or secret manager. See the [hosted MCP setup guide](https://docs.firecrawl.dev/mcp-server) and the [agent onboarding guide](https://www.firecrawl.dev/agent-onboarding/SKILL.md) for client-specific instructions.

Search-only endpoint

A fixed-scope search surface is also hosted at:

https://mcp.firecrawl.dev/v2/mcp-search

It exposes a fixed set of eight tools: `firecrawl_search`, `firecrawl_developer_search`, the four `firecrawl_research_*` tools, and the two Alexandria tools `firecrawl_find_tools` and `firecrawl_scrape`. Its `firecrawl_search` fetches no page content, and the surface has its own OAuth identity; the full endpoint above is unchanged. It backs a published connector listing, so its tool set is a contract rather than a profile to tune. See [docs/search-profile.md](docs/search-profile.md) for the full contract and what a change to it involves.

For packaged MCP workflows in ChatGPT, Codex, or Claude Code, see [MCP plugin packages](plugins/README.md).

Running with npx

env FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp

Manual Installation

npm install -g firecrawl-mcp

Running on Cursor

Configuring Cursor 🖥️ Note: Requires Cursor version 0.45.6+ For the most up-to-date configuration instructions, please refer to the official Cursor documentation on configuring MCP servers: [Cursor MCP Server Configuration Guide](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers)

To configure Firecrawl MCP in Cursor **v0.48.6**

1. Open Cursor Settings 2. Go to Features > MCP Servers 3. Click "+ Add new global MCP server" 4. Enter the following code:

   {
     "mcpServers": {
       "firecrawl-mcp": {
         "command": "npx",
         "args": ["-y", "firecrawl-mcp"],
         "env": {
           "FIRECRAWL_API_KEY": "YOUR-API-KEY"
         }
       }
     }
   }

To configure Firecrawl MCP in Cursor **v0.45.6**

1. Open Cursor Settings 2. Go to Features > MCP Servers 3. Click "+ Add New MCP Server" 4. Enter the following: - Name: "firecrawl-mcp" (or your preferred name) - Type: "command" - Command: `env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp`

> If you are using Windows and are running into issues, try `cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp"`

Replace `your-api-key` with your Firecrawl API key. If you don't have one yet, you can create an account and get it from https://www.firecrawl.dev/app/api-keys

After adding, refresh the MCP server list to see the new tools. The Composer Agent will automatically use Firecrawl MCP when appropriate, but you can explicitly request it by describing your web scraping needs. Access the Composer via Command+L (Mac), select "Agent" next to the submit button, and enter your query.

Running on Windsurf

Add this to your `./codeium/windsurf/model_config.json`:

{
  "mcpServers": {

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,532 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <a name="readme-top"></a>
  3. <img
  4. src="https://raw.githubusercontent.com/firecrawl/firecrawl-mcp-server/main/img/fire.png"
  5. height="140"
  6. >
  7. </div>
  8. # Firecrawl MCP Server
  9. A Model Context Protocol (MCP) server that brings [Firecrawl](https://github.com/firecrawl/firecrawl), the context API for AI agents, to MCP-compatible clients: search, scrape, and interact with the live web and get back clean Markdown or structured data.
  10. > Big thanks to [@vrknetha](https://github.com/vrknetha), [@knacklabs](https://www.knacklabs.ai) for the initial implementation!
  11. ## Features
  12. - Search the web, optionally with full page content for each result
  13. - Search indexes for developer sources (GitHub issues, merged pull requests, READMEs, and docs), US government sources, and scientific papers (PubMed, bioRxiv, medRxiv, arXiv)
  14. - Look up a protein's curated subcellular location and function in UniProtKB/Swiss-Prot, with the evidence and papers behind each statement
  15. - Scrape any URL into clean Markdown
  16. - Parse PDFs and documents
  17. - Crawl a site for content from many pages, or map it to discover its URLs
  18. - Interact with pages in a real browser: click, type, fill forms, and navigate dynamic pages
  19. - Run Agent jobs for multi-source research that returns structured data
  20. - Monitor pages and get notified when their content changes
  21. - Check current and historical Firecrawl credit usage
  22. - Automatic retries and rate limiting
  23. - Cloud and self-hosted support
  24. - SSE support
  25. > Play around with [our MCP Server on MCP.so's playground](https://mcp.so/playground?server=firecrawl-mcp-server) or on [Klavis AI](https://www.klavis.ai/mcp-servers).
  26. ## When to Use This Server
  27. - Use `firecrawl_scrape` when you have a known URL and want its content as markdown, then extract the requested fields yourself.
  28. - Use `firecrawl_map` when you need to discover URLs on a site without fetching their content.
  29. - Use `firecrawl_crawl` when you need content from many pages under a site; set `limit`, `includePaths`/`excludePaths`, or `maxDiscoveryDepth` to bound it.
  30. - Use `firecrawl_search` when you're starting from a query rather than a URL and want ranked web results. Results carry excerpts; fetch full pages with `firecrawl_scrape` on the URLs you need. `scrapeOptions` fetches every result's page in the same call and bills each as a scrape, so keep it for the full text of a few results (the search-only endpoint never fetches content).
  31. - Use `firecrawl_interact` when a page needs a click, type, or navigate action before you can read it: pass a `url` for a fresh page or a `scrapeId` to continue on one you already scraped.
  32. - Use the `firecrawl_monitor_*` tools when the same page needs to be checked on a recurring schedule with diffs and change alerts, rather than fetched once.
  33. - Use `firecrawl_credit_usage` to check credits left or what credits were spent on, by month or day, optionally broken down by endpoint or API key.
  34. - Consider something else when you need to hold a browser session open across many of your own steps with your own retry and termination logic: each `firecrawl_interact` call runs one `prompt` or `code` turn to completion and returns control. The session can persist across calls via `scrapeId` and ends with `firecrawl_interact_stop`, but you cannot drive it interactively step-by-step from the client side within a single call.
  35. This server lists 34 tools when the full profile registers with default settings (feedback tools included, not running in local-keyless mode). Setting `FIRECRAWL_NO_SEARCH_FEEDBACK=1` and/or `FIRECRAWL_NO_ENDPOINT_FEEDBACK=1` removes the corresponding feedback tools and reduces this count, as does local keyless startup. For clients with a tool-slot limit: the hosted keyless endpoint (`https://mcp.firecrawl.dev/v2/mcp`, no API key) exposes only 3 (`firecrawl_scrape`, `firecrawl_search`, `firecrawl_parse`), and the dedicated [search-only endpoint](#search-only-endpoint) (`https://mcp.firecrawl.dev/v2/mcp-search`) exposes a fixed set of 12 tools (search, developer, government, and research search, Alexandria catalogue lookup and execution, people and company search and enrichment, and job postings).
  36. ## Installation
  37. ### Hosted MCP (keyless free tier)
  38. Connect to the remote hosted server with no setup:
  39. ```
  40. https://mcp.firecrawl.dev/v2/mcp
  41. ```
  42. On the keyless free tier, `scrape`, `search`, and `parse` work without an API key (rate-limited). Other tools such as `crawl`, `map`, and `agent` still need a key.
  43. Prefer OAuth or an API key whenever the human can sign up. It unlocks the full tool set and higher limits.
  44. For an interactive account connection, configure your MCP client to use this server URL. This is an MCP endpoint, **not a browser page**; use the client's account-connection flow and do not add a second Firecrawl server entry when reconnecting:
  45. ```
  46. https://mcp.firecrawl.dev/v2/mcp-oauth
  47. ```
  48. For an API-key connection (for example, an unattended integration), keep the server URL as:
  49. ```
  50. https://mcp.firecrawl.dev/v2/mcp
  51. ```
  52. Then configure the client's secure header or secret setting with:
  53. ```
  54. Authorization: Bearer <FIRECRAWL_API_KEY>
  55. ```
  56. Never put an API key in the server URL. Never put an API key in an agent chat. Configure it directly in the client or secret manager. See the [hosted MCP setup guide](https://docs.firecrawl.dev/mcp-server) and the [agent onboarding guide](https://www.firecrawl.dev/agent-onboarding/SKILL.md) for client-specific instructions.
  57. #### Naming your integration
  58. An integration that connects over HTTP can name itself with an `X-Firecrawl-Origin` header, for example `X-Firecrawl-Origin: my-agent`. The server reports it to Firecrawl as the request origin `mcp-my-agent@<server version>`, in place of the client name or User-Agent it would otherwise report. Use letters, digits and dashes: each run of other characters becomes one dash, leading and trailing dashes are dropped, and the name is cut at 48 characters. Tool results are unaffected; only the origin sent to the Firecrawl API (and passed to an embedder's `beforeKeylessRequest`) changes.
  59. #### Search-only endpoint
  60. A fixed-scope search surface is also hosted at:
  61. ```
  62. https://mcp.firecrawl.dev/v2/mcp-search
  63. ```
  64. It exposes a fixed set of twelve tools: `firecrawl_search`, `firecrawl_developer_search`, `firecrawl_gov_search`, the four `firecrawl_research_*` paper tools, the two Alexandria tools `firecrawl_find_tools` and `firecrawl_scrape`, and the [enrich tools](#15b-enrich-tools) `people_company_search` and `people_company_enrich`, and the [jobs tool](#15c-jobs-tool-jobs_search) `jobs_search`. Its `firecrawl_search` fetches no page content.
  65. ### Running with npx
  66. ```bash
  67. env FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp
  68. ```
  69. ### Manual Installation
  70. ```bash
  71. npm install -g firecrawl-mcp
  72. ```
  73. ### Running on Cursor
  74. Configuring Cursor 🖥️
  75. Note: Requires Cursor version 0.45.6+
  76. For the most up-to-date configuration instructions, please refer to the official Cursor documentation on configuring MCP servers:
  77. [Cursor MCP Server Configuration Guide](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers)
  78. To configure Firecrawl MCP in Cursor **v0.48.6**
  79. 1. Open Cursor Settings
  80. 2. Go to Features > MCP Servers
  81. 3. Click "+ Add new global MCP server"
  82. 4. Enter the following code:
  83. ```json
  84. {
  85. "mcpServers": {
  86. "firecrawl-mcp": {
  87. "command": "npx",
  88. "args": ["-y", "firecrawl-mcp"],
  89. "env": {
  90. "FIRECRAWL_API_KEY": "YOUR-API-KEY"
  91. }
  92. }
  93. }
  94. }
  95. ```
  96. To configure Firecrawl MCP in Cursor **v0.45.6**
  97. 1. Open Cursor Settings
  98. 2. Go to Features > MCP Servers
  99. 3. Click "+ Add New MCP Server"
  100. 4. Enter the following:
  101. - Name: "firecrawl-mcp" (or your preferred name)
  102. - Type: "command"
  103. - Command: `env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp`
  104. > If you are using Windows and are running into issues, try `cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp"`
  105. Replace `your-api-key` with your Firecrawl API key. If you don't have one yet, you can create an account and get it from https://www.firecrawl.dev/app/api-keys
  106. After adding, refresh the MCP server list to see the new tools. The Composer Agent will automatically use Firecrawl MCP when appropriate, but you can explicitly request it by describing what you need from the web. Access the Composer via Command+L (Mac), select "Agent" next to the submit button, and enter your query.
  107. ### Running on Windsurf
  108. Add this to your `./codeium/windsurf/model_config.json`:
  109. ```json
  110. {
  111. "mcpServers": {
  112. "mcp-server-firecrawl": {
  113. "command": "npx",
  114. "args": ["-y", "firecrawl-mcp"],
  115. "env": {
  116. "FIRECRAWL_API_KEY": "YOUR_API_KEY"
  117. }
  118. }
  119. }
  120. }
  121. ```
  122. ### Running with Streamable HTTP Local Mode
  123. To run the server using Streamable HTTP locally instead of the default stdio transport:
  124. ```bash
  125. env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp
  126. ```
  127. Use the url: http://localhost:3000/mcp
  128. In this mode the server only answers requests addressed to `localhost`, `127.0.0.1` or `[::1]` (on any port), plus the address in `HOST` when it isn't `0.0.0.0` or `::`. A request whose `Host` header names another host, or whose `Origin` header names another site, gets `403`, and CORS headers echo an allowed origin instead of `*`. `GET` and `HEAD` requests to `/health` are answered whatever the host, so health checks keep working, and the server logs a line naming `FIRECRAWL_MCP_ALLOWED_HOSTS` for every request it refuses. This stops web pages you visit from calling the local server through DNS rebinding or cross-origin requests and using its `FIRECRAWL_API_KEY`.
  129. To reach the server under another name or address, such as a hostname behind a reverse proxy or a LAN IP, list it in `FIRECRAWL_MCP_ALLOWED_HOSTS` (comma-separated; ports are ignored). The same list decides which browser origins may call the server. A reverse proxy on the same machine can keep the default bind address:
  130. ```bash
  131. env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
  132. FIRECRAWL_MCP_ALLOWED_HOSTS=mcp.home.lan npx -y firecrawl-mcp
  133. ```
  134. Clients on other machines also need the server to listen on a non-loopback address, so set `HOST` too. Every client that can reach the port is then served with the server's `FIRECRAWL_API_KEY`, so do this only on a network you trust:
  135. ```bash
  136. env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY HOST=0.0.0.0 \
  137. FIRECRAWL_MCP_ALLOWED_HOSTS=192.168.1.20 npx -y firecrawl-mcp
  138. ```
  139. `FIRECRAWL_MCP_ALLOWED_HOSTS=*` turns the check off and restores the wildcard CORS header. Only do that when something in front of the server checks hosts and origins itself.
  140. ### Running with Docker
  141. The `ghcr.io/firecrawl/firecrawl-mcp-server` image runs the same server as `npx -y firecrawl-mcp`. Every build from `main` is tagged `latest`, `v<package version>` and `sha-<commit sha>`. `v<package version>` moves to the newest build of that version, so pin `sha-<commit sha>` (or a digest) when you need a fixed image.
  142. stdio (the default), for MCP clients that launch the server as a command:
  143. ```bash
  144. docker run -i --rm -e FIRECRAWL_API_KEY=fc-YOUR_API_KEY ghcr.io/firecrawl/firecrawl-mcp-server:latest
  145. ```
  146. ```json
  147. {
  148. "mcpServers": {
  149. "firecrawl-mcp": {
  150. "command": "docker",
  151. "args": ["run", "-i", "--rm", "-e", "FIRECRAWL_API_KEY", "ghcr.io/firecrawl/firecrawl-mcp-server:latest"],
  152. "env": {
  153. "FIRECRAWL_API_KEY": "YOUR_API_KEY"
  154. }
  155. }
  156. }
  157. }
  158. ```
  159. Streamable HTTP, served at `http://localhost:3000/mcp`:
  160. ```bash
  161. docker run --rm -p 127.0.0.1:3000:3000 \
  162. -e HTTP_STREAMABLE_SERVER=true \
  163. -e FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
  164. ghcr.io/firecrawl/firecrawl-mcp-server:latest
  165. ```
  166. The image sets `HOST=0.0.0.0` and `PORT=3000`; override `PORT` (and the `-p` mapping) to listen elsewhere. The server uses the container's `FIRECRAWL_API_KEY` for requests that don't send their own credential, so the example publishes the port on `127.0.0.1` only; don't expose it more widely unless clients must supply their own key. Set `FIRECRAWL_API_URL` to use a self-hosted Firecrawl API. The container runs as the unprivileged `node` user. The server answers only `localhost`, `127.0.0.1` and `[::1]` in the `Host` and `Origin` headers, so the `-p 127.0.0.1:3000:3000` mapping works as is; to reach it under another name, set `-e FIRECRAWL_MCP_ALLOWED_HOSTS=<host>` (see [Streamable HTTP local mode](#running-with-streamable-http-local-mode)).
  167. ### Running on VS Code
  168. For one-click installation, click one of the install buttons below...
  169. [![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=firecrawl&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22Firecrawl%20API%20Key%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22firecrawl-mcp%22%5D%2C%22env%22%3A%7B%22FIRECRAWL_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-NPM-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=firecrawl&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22Firecrawl%20API%20Key%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22firecrawl-mcp%22%5D%2C%22env%22%3A%7B%22FIRECRAWL_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D&quality=insiders)
  170. For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.
  171. ```json
  172. {
  173. "mcp": {
  174. "inputs": [
  175. {
  176. "type": "promptString",
  177. "id": "apiKey",
  178. "description": "Firecrawl API Key",
  179. "password": true
  180. }
  181. ],
  182. "servers": {
  183. "firecrawl": {
  184. "command": "npx",
  185. "args": ["-y", "firecrawl-mcp"],
  186. "env": {
  187. "FIRECRAWL_API_KEY": "${input:apiKey}"
  188. }
  189. }
  190. }
  191. }
  192. }
  193. ```
  194. Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others:
  195. ```json
  196. {
  197. "inputs": [
  198. {
  199. "type": "promptString",
  200. "id": "apiKey",
  201. "description": "Firecrawl API Key",
  202. "password": true
  203. }
  204. ],
  205. "servers": {
  206. "firecrawl": {
  207. "command": "npx",
  208. "args": ["-y", "firecrawl-mcp"],
  209. "env": {
  210. "FIRECRAWL_API_KEY": "${input:apiKey}"
  211. }
  212. }
  213. }
  214. }
  215. ```
  216. ## Configuration
  217. ### Environment Variables
  218. #### Required for Cloud API
  219. - `FIRECRAWL_API_KEY`: Your Firecrawl API key
  220. - Required when using cloud API (default)
  221. - Optional when using self-hosted instance with `FIRECRAWL_API_URL`
  222. - `FIRECRAWL_API_URL` (Optional): Custom API endpoint for self-hosted instances
  223. - Example: `https://firecrawl.your-domain.com`
  224. - If not provided, the cloud API will be used (requires API key)
  225. - Over stdio, Alexandria tools are sent to this endpoint even when no API key is set here, and it answers for the account. [Firecrawl Local](https://github.com/firecrawl/firecrawl/tree/main/apps/local) signs them with the login it holds
  226. - `FIRECRAWL_INTEGRATION` (Optional): Integration tag for apps that launch this server, such as an editor extension
  227. - Sent as the `integration` field of scrape, batch scrape, crawl, map, search, extract, agent, parse, interact and feedback requests
  228. - Use a value that starts with `_`, for example `_zed`
  229. - `FIRECRAWL_MCP_LIBRARY_SKILLS` (Optional): Set to `false` to serve the Alexandria library without skills
  230. - Every `firecrawl/library` call carries `skills: false` (through `alexandria_library_search`, `alexandria_library_read` or a `firecrawl_scrape` alexandria body), the library description and the server instructions leave out the skills folder, no skills are listed under its results, and `firecrawl_save_skill` is not registered
  231. #### Local HTTP mode
  232. - `FIRECRAWL_MCP_ALLOWED_HOSTS` (Optional): Extra host names or addresses the server answers with `HTTP_STREAMABLE_SERVER=true` or `SSE_LOCAL=true`, comma-separated
  233. - `localhost`, `127.0.0.1`, `[::1]` and a non-wildcard `HOST` are always allowed; ports are ignored
  234. - Requests whose `Host` or `Origin` header names any other host get `403`, except `GET` and `HEAD` requests to `/health`
  235. - `*` turns the check off; not used with `CLOUD_SERVICE=true`, which answers every host
  236. #### MCP OAuth (Bearer access tokens)
  237. Firecrawl issues OAuth **access tokens** (`fco_…`) via the authorization server on [firecrawl.dev](https://firecrawl.dev). This MCP server forwards whichever credential it resolves to the Firecrawl API as `Authorization: Bearer …`.
  238. - **HTTP stream transports** (`CLOUD_SERVICE=true`, `HTTP_STREAMABLE_SERVER=true`, or `SSE_LOCAL=true`): Clients should send `Authorization: Bearer <fco_access_token>` on MCP requests. An OAuth bearer token takes precedence over `x-firecrawl-api-key` / `x-api-key` when both are present.
  239. - **stdio:** Use `FIRECRAWL_OAUTH_TOKEN` for a static access token, or keep using `FIRECRAWL_API_KEY` for an API key.
  240. Use **access** tokens (`fco_…`) only. Refresh tokens (`fcr_…`) must be exchanged at the token endpoint, not passed to the scrape/search API.
  241. #### `CLOUD_SERVICE=true`
  242. `CLOUD_SERVICE=true` serves the tools over streamable HTTP on `PORT` (default `3000`, bound to `0.0.0.0`) with stricter defaults: every request must carry a credential (an API key or an OAuth access token), scrape is read-only (see the scrape tool below), and `firecrawl_parse` accepts uploads only.
  243. `FASTMCP_ENDPOINT` selects the tool surface: `/v2/mcp` (default) for the full tool set, `/v2/mcp-oauth` for the account surface, or `/v2/mcp-search` for the search-only tools (this also requires `FIRECRAWL_MCP_SEARCH_OAUTH_ONLY=true`). With the full surface, a search-only instance also starts on port `3001`; set `FIRECRAWL_MCP_SEARCH_ENABLED=false` to turn it off.
  244. ### Configuration Examples
  245. For cloud API usage:
  246. ```bash
  247. export FIRECRAWL_API_KEY=your-api-key
  248. ```
  249. For self-hosted instance:
  250. ```bash
  251. # Required for self-hosted
  252. export FIRECRAWL_API_URL=https://firecrawl.your-domain.com
  253. # Optional authentication for self-hosted
  254. export FIRECRAWL_API_KEY=your-api-key # If your instance requires auth
  255. ```
  256. ### Usage with Claude Desktop
  257. Add this to your `claude_desktop_config.json`:
  258. ```json
  259. {
  260. "mcpServers": {
  261. "mcp-server-firecrawl": {
  262. "command": "npx",
  263. "args": ["-y", "firecrawl-mcp"],
  264. "env": {
  265. "FIRECRAWL_API_KEY": "YOUR_API_KEY_HERE"
  266. }
  267. }
  268. }
  269. }
  270. ```
  271. ## How to Choose a Tool
  272. Use this guide to select the right tool for your task:
  273. - **If you know the exact URL you want:** use **scrape**, then extract the requested fields from its markdown
  274. - **If you have multiple known URLs:** call **scrape** for each URL. If you specifically need one bulk API operation, use the Firecrawl API batch endpoint outside MCP.
  275. - **If you need to discover URLs on a site:** use **map**
  276. - **If you want to search the web for info:** use **search**
  277. - **If you have a programming question** (a library, an API contract, an error message, a known bug): use **developer search**
  278. - **If you have a legal or regulatory question** (a statute, regulation, code, court opinion, or other US government publication): use the **Firecrawl Government Index**
  279. - **If you need scientific papers** (biomedical, life-science, clinical, or arXiv literature): use **research tools**, which search paper abstracts and full text. `search` with `categories: ["research"]` is a different thing: a website filter over ordinary web results.
  280. - **If you need what is known about one protein** (where it is located in the cell, what it does): use the **protein lookup**, which returns UniProt's curated statements with the evidence and papers behind each
  281. - **If you need multi-source research that returns structured data, do not know the URLs, or the answer spans several sites** (an entity plus its fields, a list, a dataset): use **agent**
  282. - **If you want to analyze a whole site or section:** use **crawl** (with limits!)
  283. - **If you need interactive browser automation** (click, type, navigate): use **interact** with a URL for a fresh page, or **scrape** + **interact** when you already scraped the page or need tighter scrape control
  284. - **If you need data from a catalogued provider** (Alexandria): search with `sources: ["alexandria"]`, explore the library and read the contract with **alexandria_library_search**, and run it with **alexandria_library_read**
  285. ### Quick Reference Table
  286. | Tool | Best for | Returns |
  287. | --------- | ---------------------------------------------- | ------------------------------------------------ |
  288. | scrape | Single page content | Markdown by default |
  289. | interact | Interact with a URL or scraped page | Execution result + scrapeId for URL mode |
  290. | map | Discovering URLs on a site | URL[] |
  291. | crawl | Multi-page extraction (with limits) | final crawl status/data after internal polling |
  292. | parse | Files and hosted upload refs | markdown, JSON, or document output |
  293. | search | Web search for info | results[] |
  294. | alexandria_library_search | Exploring the Alexandria library with shell commands | command output: file paths, READMEs, contracts |
  295. | alexandria_library_read | Running Alexandria capabilities, up to ten per call | typed, sourced records |
  296. | developer | Programming questions over developer sources | results[] with passages |
  297. | gov | US primary law and regulatory material | results[] with snippets |
  298. | agent | Multi-source research, unknown or many sites | JSON (structured data) |
  299. | monitor | Recurring page checks | monitor/check metadata and diffs |
  300. | research | Paper research (developer for repositories) | research results |
  301. | protein | One protein's curated UniProt annotation | location, function, and GO terms with evidence |
  302. ### Format Selection Guide
  303. When using `scrape`, choose the right format:
  304. - **Markdown format:** Read the page and extract the requested fields yourself.
  305. ## Available Tools
  306. ### 1. Scrape Tool (`firecrawl_scrape`)
  307. Scrape content from a single URL with advanced options.
  308. **Best for:**
  309. - Single page content extraction, when you know exactly which page contains the information.
  310. **Not recommended for:**
  311. - Extracting content from multiple pages (use repeated scrape calls for known URLs, or map + scrape to discover URLs first, or crawl for full page content)
  312. - When you're unsure which page contains the information (use search)
  313. **Common mistakes:**
  314. - Passing a list of URLs to one scrape call. Call scrape once per URL in MCP. If you specifically need one bulk API operation, use the Firecrawl API batch endpoint outside MCP.
  315. - Requesting `json` or `jsonOptions` for new MCP scrape calls. These inputs are hidden from discovery but remain accepted for compatibility with cached tool definitions.
  316. **Choosing the right format:**
  317. - **Markdown format:** Read the returned content and extract the fields you need yourself.
  318. **Prompt Example:**
  319. > "Get the product details from https://example.com/product."
  320. **Usage Example (read product details):**
  321. ```json
  322. {
  323. "name": "firecrawl_scrape",
  324. "arguments": {
  325. "url": "https://example.com/product",
  326. "formats": ["markdown"]
  327. }
  328. }
  329. ```
  330. **Usage Example (markdown format - when full content needed):**
  331. ```json
  332. {
  333. "name": "firecrawl_scrape",
  334. "arguments": {
  335. "url": "https://example.com/article",
  336. "formats": ["markdown"],
  337. "onlyMainContent": true
  338. }
  339. }
  340. ```
  341. **Usage Example (branding format - extract brand identity):**
  342. ```json
  343. {
  344. "name": "firecrawl_scrape",
  345. "arguments": {
  346. "url": "https://example.com",
  347. "formats": ["branding"]
  348. }
  349. }
  350. ```
  351. **Branding format:** Extracts comprehensive brand identity (colors, fonts, typography, spacing, logo, UI components) for design analysis or style replication.
  352. **Privacy:** Set `redactPII: true` to return content with personally identifiable information redacted.
  353. **With `CLOUD_SERVICE=true`:** scrape is read-only. It takes no browser `actions` and cannot accept provider terms. A named `profile` loads saved browser state without saving changes to it, and the full endpoint's `firecrawl_search` treats `scrapeOptions.profile` the same way. To save browser state to a profile, open the page with `firecrawl_interact` (see below). An organization admin accepts terms in the dashboard.
  354. **Returns:**
  355. - Markdown, branding profile, or other formats as specified.
  356. ### 2. Map Tool (`firecrawl_map`)
  357. Map a website to discover all indexed URLs on the site.
  358. **Best for:**
  359. - Discovering URLs on a website before deciding what to scrape
  360. - Finding specific sections of a website
  361. **Not recommended for:**
  362. - When you already know which specific URL you need (use scrape)
  363. - When you need the content of the pages (use scrape after mapping)
  364. **Common mistakes:**
  365. - Using crawl to discover URLs instead of map
  366. **Prompt Example:**
  367. > "List all URLs on example.com."
  368. **Usage Example:**
  369. ```json
  370. {
  371. "name": "firecrawl_map",
  372. "arguments": {
  373. "url": "https://example.com"
  374. }
  375. }
  376. ```
  377. **Returns:**
  378. - Array of URLs found on the site
  379. ### 3. Search Tool (`firecrawl_search`)
  380. Search the web and optionally extract content from search results.
  381. **Best for:**
  382. - Finding specific information across multiple websites, when you don't know which website has the information.
  383. - When you need the most relevant content for a query
  384. **Not recommended for:**
  385. - When you already know which website to scrape (use scrape)
  386. - When you need comprehensive coverage of a single website (use map or crawl)
  387. **Common mistakes:**
  388. - Using crawl or map for open-ended questions (use search instead)
  389. **Usage Example:**
  390. ```json
  391. {
  392. "name": "firecrawl_search",
  393. "arguments": {
  394. "query": "remote work stipend policies at tech companies",
  395. "highlights": true,
  396. "limit": 5,
  397. "lang": "en",
  398. "country": "us"
  399. }
  400. }
  401. ```
  402. To get the full text of a few results in the same call, add `"scrapeOptions": { "formats": ["markdown"], "onlyMainContent": true }`. Each fetched result is billed as a scrape, so for most questions use the excerpts and `firecrawl_scrape` only the URLs you need.
  403. Set `highlights` to `true` to request query-relevant highlights or `false` to keep the original search snippets. Omit it to use the API's default behavior.
  404. Add `"sources": ["alexandria"]` for semantic tool discovery in `data.tools`, optionally mixed with web/news/images. A query is required. Use `alexandria_library_search` to explore the whole library and read contracts (`firecrawl_find_tools` on the search-only endpoint); see [Alexandria Tools](#15-alexandria-tools).
  405. For scientific papers, see [Research Tools](#12-research-tools-firecrawl_research_): they search paper abstracts and full text, while `categories: ["research"]` here filters ordinary web results to research-affiliated websites.
  406. **Returns:**
  407. - Search results grouped by source (`data.web`, `data.images`, `data.news`), with optional scraped content, plus an `id` field. Every result carries a `source` and a 1-indexed `position`, numbered from 1 within its own group — copy the pair straight into `firecrawl_search_feedback`'s `valuableResults` rather than counting array elements. Pass that `id` to `firecrawl_search_feedback` after you've used the results to refund 1 credit (search costs 2) and improve search quality.
  408. **Prompt Example:**
  409. > "Compare remote work stipend policies across tech companies."
  410. ### 3b. Search Feedback Tool (`firecrawl_search_feedback`)
  411. Sends structured feedback on a previous `firecrawl_search` result. The first feedback per search id refunds 1 credit and improves Firecrawl's search quality. Idempotent per search id.
  412. **Call this after every search you actually use** (or that didn't help). Bad/partial feedback with `missingContent` is just as valuable as good feedback.
  413. **Opt out:** set `FIRECRAWL_NO_SEARCH_FEEDBACK=1` (or `FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1`) in the environment when starting the MCP server. The `firecrawl_search_feedback` tool will not be registered, so agents can't call it. Team admins can also disable feedback server-side; in that case the tool is registered but always returns `feedbackErrorCode: "TEAM_OPTED_OUT"`.
  414. **Most important field:** `missingContent`. It's an array of specific pieces of content the agent expected to find but did not. One entry per missing topic; these aggregate across teams and tell us what to index next. For useful results, use `valuableResults` with the `source`/`position` pair stamped on each result — results are grouped and each group is numbered from 1 independently, so both are required. List **every** useful result (unlisted results are treated as not useful), and reserve `valuableSources` for useful URLs that were not among the returned results.
  415. **Daily refund cap (per team, per UTC day, default 100 credits).** Once a team's `creditsRefundedToday` reaches `dailyRefundCap`, further submissions still record feedback but no longer refund credits. The response sets `dailyCapReached: true`. Agents should stop calling this tool for the rest of the UTC day when they see that flag.
  416. **Usage Example:**
  417. ```json
  418. {
  419. "name": "firecrawl_search_feedback",
  420. "arguments": {
  421. "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
  422. "rating": "good",
  423. "valuableResults": [
  424. { "source": "web", "position": 1 },
  425. { "source": "web", "position": 3 },
  426. { "source": "news", "position": 2, "reason": "Broke the pricing change." }
  427. ],
  428. "valuableSources": [
  429. {
  430. "url": "https://docs.firecrawl.dev/pricing",
  431. "reason": "Not in the results; found via a result's pricing link. Answered the question."
  432. }
  433. ],
  434. "missingContent": [
  435. {
  436. "topic": "Pricing for the search endpoint",
  437. "description": "No pricing tier table for /search specifically."
  438. },
  439. { "topic": "Per-team rate limits" }
  440. ],
  441. "querySuggestions": "Boost docs.firecrawl.dev for queries that mention 'firecrawl'"
  442. }
  443. }
  444. ```
  445. **Returns:**
  446. - `{ success, feedbackId, creditsRefunded, alreadySubmitted? }` JSON.
  447. ### 3c. Generic Feedback Tool (`firecrawl_feedback`)
  448. Sends structured feedback for a completed v2 endpoint job through `/v2/feedback`.
  449. Use this for endpoint-level feedback on `scrape`, `parse`, `map`, or `search`
  450. jobs. For search-result quality specifically, prefer
  451. `firecrawl_search_feedback` because it includes search-specific guidance.
  452. Keep feedback concise: use issue codes, tags, short notes, URLs, page numbers,
  453. and small metadata objects. Do not include raw scrape/parse outputs.
  454. **Opt out:** set `FIRECRAWL_NO_ENDPOINT_FEEDBACK=1` (or `FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK=1`) in the environment when starting the MCP server. The `firecrawl_feedback` tool will not be registered, so agents cannot call it.
  455. **Usage Example:**
  456. ```json
  457. {
  458. "name": "firecrawl_feedback",
  459. "arguments": {
  460. "endpoint": "scrape",
  461. "jobId": "0193f6c5-1234-7890-abcd-1234567890ab",
  462. "rating": "partial",
  463. "issues": ["missing_markdown"],
  464. "tags": ["docs"],
  465. "note": "The pricing table was missing from the markdown output.",
  466. "url": "https://example.com/pricing",
  467. "pageNumbers": [1],
  468. "metadata": {
  469. "format": "markdown"
  470. }
  471. }
  472. }
  473. ```
  474. **Returns:**
  475. - `{ success, feedbackId, creditsRefunded, creditsRefundedToday?, dailyRefundCap?, dailyCapReached?, websiteCapReached?, alreadySubmitted?, warning? }` JSON.
  476. ### 4. Crawl Tool (`firecrawl_crawl`)
  477. Starts a crawl job, polls until it reaches a terminal state, and returns the final crawl status/data.
  478. **Best for:**
  479. - Extracting content from multiple related pages, when you need comprehensive coverage.
  480. **Not recommended for:**
  481. - Extracting content from a single page (use scrape)
  482. - When token limits are a concern (use map + scrape for tighter control)
  483. - When you need fast results (crawling can be slow)
  484. **Warning:** Crawl responses can be very large and may exceed token limits. Limit the crawl depth and number of pages, or use map + scrape for tighter control.
  485. **Common mistakes:**
  486. - Setting limit or maxDiscoveryDepth too high (causes token overflow)
  487. - Using crawl for a single page (use scrape instead)
  488. **Prompt Example:**
  489. > "Get all blog posts from the first two levels of example.com/blog."
  490. **Usage Example:**
  491. ```json
  492. {
  493. "name": "firecrawl_crawl",
  494. "arguments": {
  495. "url": "https://example.com/blog/*",
  496. "maxDiscoveryDepth": 2,
  497. "limit": 100,
  498. "allowExternalLinks": false,
  499. "deduplicateSimilarURLs": true
  500. }
  501. }
  502. ```
  503. **Returns:**
  504. - Final crawl status and data after internal polling, including `id`, `status`, `completed`, `total`, `creditsUsed`, `expiresAt`, `next`, and `data`. Use the returned `id` with `firecrawl_check_crawl_status` if you need to re-check the job later.
  505. ### 5. Check Crawl Status (`firecrawl_check_crawl_status`)
  506. Check the status and results of an existing crawl job by ID.
  507. ```json
  508. {
  509. "name": "firecrawl_check_crawl_status",
  510. "arguments": {
  511. "id": "550e8400-e29b-41d4-a716-446655440000"
  512. }
  513. }
  514. ```
  515. **Returns:**
  516. - Response includes the status of the crawl job:
  517. ### 6. Parse Tool (`firecrawl_parse`)
  518. Parse local files or hosted upload references with Firecrawl's `/v2/parse` endpoint.
  519. **Best for:** PDFs, Word documents, spreadsheets, HTML files, and other documents that need markdown or structured JSON output. The hosted endpoint uses a two-step upload flow; local direct file reads require a self-hosted `FIRECRAWL_API_URL`.
  520. **Not recommended for:** Remote URLs (use scrape), multiple files in one call (call parse once per file), or browser-only actions such as screenshots and clicks.
  521. **Hosted endpoint:** it cannot read your filesystem. Call `firecrawl_parse` with `filePath` to receive a short-lived upload command and `nextToolCall`, upload the file locally, then call `firecrawl_parse` again with the returned `uploadRef`. The upload step requires Firecrawl auth or the keyless tier. In local `npx firecrawl-mcp` mode, direct file parsing currently requires `FIRECRAWL_API_URL` pointing to a self-hosted Firecrawl API; a plain cloud API-key-only local server cannot read and upload files through this tool.
  522. **Usage Example:**
  523. ```json
  524. {
  525. "name": "firecrawl_parse",
  526. "arguments": {
  527. "filePath": "/absolute/path/to/document.pdf",
  528. "formats": ["markdown"],
  529. "parsers": ["pdf"],
  530. "zeroDataRetention": true
  531. }
  532. }
  533. ```
  534. **Returns:** Parsed document content or hosted upload instructions with a `nextToolCall`.
  535. ### 7. Structured data from a known page
  536. Call `firecrawl_scrape` once per URL with `formats: ["markdown"]`, then extract the requested fields from the returned content yourself.
  537. ```json
  538. {
  539. "name": "firecrawl_scrape",
  540. "arguments": {
  541. "url": "https://example.com/product",
  542. "formats": ["markdown"]
  543. }
  544. }
  545. ```
  546. When the URLs are not known or the data spans several sites, use `firecrawl_agent` for multi-source research.
  547. ### 8. Agent Tool (`firecrawl_agent`)
  548. Autonomous web research agent that returns structured data when you do not know the URLs or the answer spans several sites. Describe the fields you need, optionally pass a JSON schema and seed URLs, and the agent searches, navigates, reads pages, and returns JSON assembled across sources. Use it for an entity plus its fields, for lists and datasets, and for pages that need navigation to reach the data. For one known URL use `firecrawl_scrape` with markdown and extract the requested fields yourself.
  549. **How it works:**
  550. The agent performs web searches, follows links, reads pages, and gathers data autonomously. This runs **asynchronously** - it returns a job ID immediately, and you poll `firecrawl_agent_status` to check when complete and retrieve results.
  551. **Async workflow:**
  552. 1. Call `firecrawl_agent` with your prompt/schema → returns job ID
  553. 2. Do other work while the agent researches (can take minutes for complex queries)
  554. 3. Poll `firecrawl_agent_status` with the job ID to check progress
  555. 4. When status is "completed", the response includes the extracted data
  556. **Best for:**
  557. - Complex research tasks where you don't know the exact URLs
  558. - Multi-source data gathering
  559. - Finding information scattered across the web
  560. - Tasks where you can do other work while waiting for results
  561. **Not recommended for:**
  562. - Simple single-page scraping where you know the URL (use scrape with markdown and extract the requested fields yourself)
  563. **Arguments:**
  564. - `prompt`: Natural language description of the data you want (required, max 10,000 characters)
  565. - `urls`: Optional array of URLs to focus the agent on specific pages
  566. - `schema`: Optional JSON schema for structured output
  567. - `effort`: Optional. `"low"`, `"medium"` or `"high"` reasoning budget for the agent task.
  568. - `maxCredits`: Optional positive integer. Spending limit in credits for this run. The API defaults to 2,500 when omitted, and caps a free request at 2,500.
  569. - `strictConstrainToURLs`: Optional boolean. If `true`, the agent only visits the URLs in `urls`.
  570. - `threadId`: Optional. Continue an existing thread: the `threadId` from an earlier `firecrawl_agent` or `firecrawl_agent_status` result. Omit to start a new thread. On a follow-up, omitted `mode`, `urls`, `schema` and `exchange` settings carry over from the previous turn.
  571. - `mode`: Optional. `"extract"` (default) returns the complete structured result every turn. `"chat"` lets a follow-up that asks for no new data get a short reply in `message` instead of a re-run; `exchange.requireApproval` needs it.
  572. - `exchange`: Optional. Alexandria provider settings for this turn, forwarded as-is to `POST /v2/agent`:
  573. - `enabled`, `toolkits` (up to 5 provider slugs), `maxCalls` (1 to 30), `requireApproval` (paid calls end the turn with a `pendingApproval`; needs `mode: "chat"` on the same call, even on a follow-up)
  574. - `onTermsRequired`: what to do when an Alexandria provider the agent would use needs data terms your team has not accepted. Gated providers are never called in any mode. Omitted on a follow-up keeps the previous turn's value.
  575. - `"skip"` (default): answer with accepted providers only. `exchange.skippedProviders` on the status result lists the gated providers that would have helped.
  576. - `"ask"`: the same, plus a terms `pendingApproval` and `exchange.requiresAction` with the approval ID and provider requirements. Read terms with `terms/show`; an organization admin accepts them in the Firecrawl dashboard.
  577. - `approve`: `{ approvalId, callIds?, always? }` answers yes to the `pendingApproval` the previous turn ended on. `callIds` and `always` apply to paid-call approvals only.
  578. - `decline`: `{ approvalId }` answers no. A declined terms offer keeps those providers out of the rest of the thread.
  579. - `approve` and `decline` need `threadId`, and only one of them can be sent.
  580. **Provider terms (ask mode):** there is no auto-accept mode. When a turn ends on a terms offer, the status result carries `pendingApproval` (`kind: "terms"`) and `exchange.requiresAction` with the `approvalId` and provider requirements. Any `terms/accept` descriptor in that API payload is unavailable through MCP. To use the provider:
  581. 1. Show the user the terms (`terms/show` through `alexandria_library_read`).
  582. 2. Direct an organization admin to accept the terms at the provider's URL, or [data sources settings](https://www.firecrawl.dev/app/settings?tab=data-sources). A data request is not consent.
  583. 3. Wait for the admin to confirm acceptance in the dashboard.
  584. 4. Continue the same thread: call `firecrawl_agent` with the same `threadId` and `exchange.approve: { "approvalId": "..." }`. This resumes research and does not accept terms.
  585. If the user says no, call `firecrawl_agent` with the same `threadId` and `exchange.decline: { "approvalId": "..." }` instead.
  586. **Prompt Example:**
  587. > "Find the founders of Firecrawl and their backgrounds"
  588. **Usage Example (start agent, then poll for results):**
  589. ```json
  590. {
  591. "name": "firecrawl_agent",
  592. "arguments": {
  593. "prompt": "Find the top 5 AI startups founded in 2024 and their funding amounts",
  594. "schema": {
  595. "type": "object",
  596. "properties": {
  597. "startups": {
  598. "type": "array",
  599. "items": {
  600. "type": "object",
  601. "properties": {
  602. "name": { "type": "string" },
  603. "funding": { "type": "string" },
  604. "founded": { "type": "string" }
  605. }
  606. }
  607. }
  608. }
  609. }
  610. }
  611. }
  612. ```
  613. Then poll with `firecrawl_agent_status` using the returned job ID.
  614. **Usage Example (with URLs - agent focuses on specific pages):**
  615. ```json
  616. {
  617. "name": "firecrawl_agent",
  618. "arguments": {
  619. "urls": ["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
  620. "prompt": "Compare the features and pricing information from these pages"
  621. }
  622. }
  623. ```
  624. **Usage Example (follow-up on the same thread):**
  625. ```json
  626. {
  627. "name": "firecrawl_agent",
  628. "arguments": {
  629. "prompt": "Only keep the startups based in Europe",
  630. "threadId": "0199a1b2-0000-7000-8000-000000000031"
  631. }
  632. }
  633. ```
  634. **Usage Example (continue the thread after an admin confirmed dashboard acceptance):**
  635. ```json
  636. {
  637. "name": "firecrawl_agent",
  638. "arguments": {
  639. "prompt": "The admin confirmed acceptance of the Apollo terms in the dashboard. Continue.",
  640. "threadId": "0199a1b2-0000-7000-8000-000000000031",
  641. "exchange": { "approve": { "approvalId": "0199a1b2-0000-7000-8000-000000000033" } }
  642. }
  643. }
  644. ```
  645. **Returns:**
  646. - Job ID for status checking, plus `threadId` and `threadTurn`. Use `firecrawl_agent_status` to poll for results.
  647. ### 9. Check Agent Status (`firecrawl_agent_status`)
  648. Check the status of an agent job and retrieve results when complete. Use this to poll for results after starting an agent.
  649. **Polling pattern:** Agent research can take minutes for complex queries. Poll this endpoint periodically (e.g., every 10-30 seconds) until status is "completed" or "failed".
  650. ```json
  651. {
  652. "name": "firecrawl_agent_status",
  653. "arguments": {
  654. "id": "550e8400-e29b-41d4-a716-446655440000"
  655. }
  656. }
  657. ```
  658. **Possible statuses:**
  659. - `processing`: Agent is still researching - check back later
  660. - `completed`: Research finished - response includes the extracted data
  661. - `failed`: An error occurred
  662. ### 10. Interact Tool (`firecrawl_interact`)
  663. Interact with a fresh URL or with a page that was already opened by `firecrawl_scrape`.
  664. **Best for:** Clicking, typing, navigating, and extracting state from dynamic pages without restoring the deprecated browser tools.
  665. **Usage options:**
  666. - Pass `url` to scrape and open a page for interaction in one MCP call.
  667. - Pass `scrapeId` to continue interacting with an existing scraped page.
  668. - To save browser state (cookies, localStorage) to a named profile, pass `url` with `scrapeOptions: { "profile": { "name": "my-profile", "saveChanges": true } }`. The state is saved when `firecrawl_interact_stop` ends the session.
  669. - Pass exactly one of `url` or `scrapeId`, plus either `prompt` or `code`.
  670. **Usage Example:**
  671. ```json
  672. {
  673. "name": "firecrawl_interact",
  674. "arguments": {
  675. "url": "https://example.com",
  676. "prompt": "Click the pricing link and summarize the visible plans"
  677. }
  678. }
  679. ```
  680. **Returns:** Interaction result and, for URL mode, the derived `scrapeId` for follow-up or cleanup.
  681. ### 11. Stop Interact Tool (`firecrawl_interact_stop`)
  682. Stop an interact session for a scraped page when you are done interacting.
  683. ```json
  684. {
  685. "name": "firecrawl_interact_stop",
  686. "arguments": {
  687. "scrapeId": "scrape-id-here"
  688. }
  689. }
  690. ```
  691. ### 12. Research Tools (`firecrawl_research_*`)
  692. Search and inspect papers through the research MCP tools. For GitHub repositories, issues, and pull requests, use `firecrawl_developer_search`.
  693. **Covers:** paper abstracts and full text across biomedical, life-science, and clinical literature (PubMed, bioRxiv, medRxiv) alongside arXiv and other scientific sources.
  694. **Available research tools:**
  695. - `firecrawl_research_search_papers`: search paper metadata and abstracts with a natural-language query, with optional author, category, and date filters.
  696. - `firecrawl_research_inspect_paper`: retrieve canonical metadata for one paper ID (arXiv, PMC, PMID, or DOI).
  697. - `firecrawl_research_related_papers`: expand from one or more anchor papers through the citation graph.
  698. - `firecrawl_research_read_paper`: read full-text passages from a specific paper.
  699. - `firecrawl_research_lookup_protein`: look up one protein in UniProtKB/Swiss-Prot and return its curated subcellular location, function, and GO cellular-component terms, each with its evidence and cited papers.
  700. **Best for:** Literature review, paper lookup, and repository discovery workflows where the agent needs a focused research surface instead of general web search.
  701. `firecrawl_search` with `categories: ["research"]` is a different surface: it filters ordinary web results to research-affiliated websites and returns page snippets, not paper records. Use the paper tools when the question is about the literature itself, and pass several distinct framings of the same question, since they surface different papers than a single query does.
  702. #### Protein lookup (`firecrawl_research_lookup_protein`)
  703. Look up one protein in UniProtKB/Swiss-Prot, the reviewed section of UniProt, and get what its curators state about it.
  704. **Best for:** A question about one named protein: where it is located in the cell, what it does, or which cellular-component terms it has. For a free-text question, a topic, or a list of proteins, use `firecrawl_research_search_papers`.
  705. **Arguments:**
  706. ```json
  707. {
  708. "name": "firecrawl_research_lookup_protein",
  709. "arguments": {
  710. "protein": "RPUSD3",
  711. "organism": "9606"
  712. }
  713. }
  714. ```
  715. - `protein` (required): one identifier: a UniProt accession (`Q6P087`), an entry name (`RUSD3_HUMAN`), a gene symbol (`RPUSD3`), or the exact protein name.
  716. - `organism`: an NCBI taxon ID (`9606`), a scientific name (`Homo sapiens`), or a UniProt common name (`Human`). It scopes gene symbols and protein names, and the default is human. Accessions and entry names ignore it.
  717. **Returns:** The entry's subcellular location, GO cellular-component terms that have experimental evidence, and function. The response body is in `structuredContent`. An abridged result:
  718. ```text
  719. # RPUSD3 (Q6P087, RUSD3_HUMAN), Homo sapiens
  720. Mitochondrial mRNA pseudouridine synthase RPUSD3. Matched by gene symbol.
  721. Subcellular location
  722. - Mitochondrion matrix. Experimental [pmid:27974379]
  723. GO cellular component (experimental)
  724. - mitochondrial matrix (GO:0005759), IDA, FlyBase [pmid:27974379]
  725. Function
  726. - Catalyzes uridine to pseudouridine isomerization (pseudouridylation) of specific mitochondrial mRNAs (mt-mRNAs) [...]. Experimental [pmid:27667664, pmid:27974379]
  727. Open a cited paper with firecrawl_research_inspect_paper or firecrawl_research_read_paper.
  728. Source: https://www.uniprot.org/uniprotkb/Q6P087/entry. Protein data from UniProtKB/Swiss-Prot release 2026_04. Copyright UniProt Consortium, https://www.uniprot.org. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/. No warranty, see https://www.uniprot.org/help/license. Selected fields, reformatted.
  729. ```
  730. Every location and function statement carries an evidence label. Among these statements, only those whose label starts with `Experimental` (`Experimental` and `Experimental, large-scale`) are measurements. `Inferred from a related protein`, `Curator inference`, `Predicted from sequence`, `Author statement`, `Imported from another database`, and `No evidence tag` are not. A statement inferred from a related protein names that entry's accession when UniProt gives one, and the `pmid:` IDs open with `firecrawl_research_inspect_paper` and `firecrawl_research_read_paper`.
  731. The GO cellular-component terms carry no such label. Every GO term listed has experimental evidence, shown by its GO code (`IDA` and the like) and the group that assigned it. A location statement and a GO term can name the same compartment with different evidence, for example a location with no evidence tag beside a GO term with `IDA`, so an answer should say which of the two the compartment rests on.
  732. A gene symbol or name that matches several entries returns the candidates, each with its accession, entry name, gene, name, and organism. Call the tool again with one accession. An input that matches no reviewed entry returns a message that says what to pass.
  733. This tool is on the full tool set only, not on the search-only endpoint. Protein data is from UniProtKB/Swiss-Prot, copyright UniProt Consortium, licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
  734. ### 13. Monitor Tools (`firecrawl_monitor_*`)
  735. Create and manage recurring page monitors. Monitors run scheduled scrapes or crawls, diff each result against the last retained snapshot, and can notify by webhook or email.
  736. **Best for:**
  737. - Watching one page or a few pages over time
  738. - Alerting on meaningful changes using a plain-English goal
  739. - Tracking check history and page-level diffs
  740. **Recommended create pattern:**
  741. Use `page` or `pages` plus `goal`. The MCP server builds the monitor request with a 30-minute schedule and the API enables meaningful-change judging automatically.
  742. Meaningful-change judging runs automatically when `goal` is set. Page webhooks expose `isMeaningful` and `judgment` on `monitor.page` events.
  743. Write goals as concise 2-3 sentence monitor instructions. Say what should trigger an alert, preserve any scope the user gave, and include intent-specific exclusions only when obvious from the request. Generic noise such as whitespace, formatting-only changes, request IDs, tracking params, generic metadata, and unrelated page chrome is already handled by the judge, so do not repeat it in every goal. If the user is vague, keep the goal broad; if they ask for broad monitoring or "any change", preserve that. If the user says they do not care about something, include that explicitly.
  744. ```json
  745. {
  746. "name": "firecrawl_monitor_create",
  747. "arguments": {
  748. "page": "https://example.com/pricing",
  749. "goal": "Alert when pricing, packaging, or launch messaging changes."
  750. }
  751. }
  752. ```
  753. **Multiple pages with webhooks:**
  754. ```json
  755. {
  756. "name": "firecrawl_monitor_create",
  757. "arguments": {
  758. "pages": ["https://example.com/pricing", "https://example.com/changelog"],
  759. "goal": "Alert when pricing, packaging, or launch messaging changes.",
  760. "webhookUrl": "https://example.com/webhooks/firecrawl"
  761. }
  762. }
  763. ```
  764. **Advanced create requests:**
  765. Pass `body` when you need crawl targets, JSON change tracking, custom retention, or explicit `judgeEnabled` control.
  766. ```json
  767. {
  768. "name": "firecrawl_monitor_create",
  769. "arguments": {
  770. "body": {
  771. "name": "Docs monitor",
  772. "schedule": { "text": "hourly", "timezone": "UTC" },
  773. "goal": "Alert when docs pages add, remove, or materially change API behavior.",
  774. "targets": [{ "type": "crawl", "url": "https://example.com/docs" }]
  775. }
  776. }
  777. }
  778. ```
  779. **Other monitor tools:**
  780. - `firecrawl_monitor_list`: list monitors.
  781. - `firecrawl_monitor_get`: get one monitor.
  782. - `firecrawl_monitor_update`: update fields including `goal`, `judgeEnabled`, `webhook`, and `notification`.
  783. - `firecrawl_monitor_run`: trigger a check now.
  784. - `firecrawl_monitor_delete`: delete a monitor (destructive; only call when the user intends to remove it).
  785. - `firecrawl_monitor_checks`: list checks, optionally filtered by status.
  786. - `firecrawl_monitor_check`: get page-level results, including `diff`, `snapshot`, `judgment.meaningful`, and `judgment.meaningfulChanges`.
  787. ### 14. Developer Search Tool (`firecrawl_developer_search`)
  788. Search an index built for coding agents. The index covers GitHub issues, merged pull requests, repository READMEs, and code documentation.
  789. **Best for:** A programming question: code behaviour, a library or framework, an API contract, an error message, or a known bug.
  790. **Arguments:**
  791. ```json
  792. {
  793. "name": "firecrawl_developer_search",
  794. "arguments": {
  795. "query": "how do I configure retries",
  796. "k": 10,
  797. "skills": "only"
  798. }
  799. }
  800. ```
  801. - `query` (required): the developer question or search phrase.
  802. - `k`: number of ranked results. The default is 10 and the maximum is 100.
  803. - `skills`: set to `"only"` to search agent-skill files alone.
  804. **Returns:** Ranked results. Each result carries an ID, a source type (`issue`, `pull_request`, `readme`, or `doc`), a URL, a title, and the matched passages in markdown.
  805. `firecrawl_search` with `categories: ["developer"]` searches the same index beside the web results. Use this tool instead when you want the matched passages, the `skills` filter, or no web results in the response. The search-only endpoint exposes both tools, and the same choice applies there.
  806. ### 14b. Government Index Search Tool (`firecrawl_gov_search`)
  807. Search primary law and regulatory material from US federal, state, and local government sources: statutes, regulations, codes, court opinions, and other government publications.
  808. **Best for:** A legal or regulatory question that needs the governing text or an official government source.
  809. **Arguments:**
  810. ```json
  811. {
  812. "name": "firecrawl_gov_search",
  813. "arguments": {
  814. "query": "excessive force claims against police officers",
  815. "k": 10,
  816. "courtType": "federal-appellate",
  817. "cites": "42 U.S.C. § 1983"
  818. }
  819. }
  820. ```
  821. - `query` (required): the legal or regulatory question or search phrase.
  822. - `k`: number of ranked results. The default is 10 and the maximum is 100.
  823. - `jurisdiction`: keep only pages of one jurisdiction: `"us"` for federal, or `"us-"` plus a two-letter state or territory code, such as `"us-ca"` or `"us-dc"`.
  824. - `court`: keep only pages labeled for one court, by CourtListener court id, such as `"scotus"`, `"ca9"` or `"nysd"`.
  825. - `courtType`: keep only pages from one type of court: `federal-supreme`, `federal-appellate`, `federal-district`, `federal-bankruptcy`, `federal-special`, `military`, `state-supreme`, `state-appellate`, `state-trial`, `state-special` or `state-attorney-general`.
  826. - `cites`: keep only pages that cite one law or case, as a printed citation such as `"42 U.S.C. § 1983"` or `"5 U.S. 137"`, or a citation id such as `"us:usc:42:1983"`.
  827. - `domain`: keep only pages from one site, such as `"irs.gov"`.
  828. The filters are optional and combine: a result must match every filter set. Filters keep only pages the index has labeled, so a filtered search can leave out relevant pages, and no results does not mean none exist. Court labels are most complete for federal courts and case-law collections.
  829. **Returns:** Ranked results. Each result carries a position, a title, a URL, and the matched snippet. The search-only endpoint exposes this tool too.
  830. `firecrawl_search` with `categories: ["gov"]` searches the same sources and returns the hits in `data.web` with `category: "gov"`. The `gov` category does not take these filters and cannot be combined with other categories.
  831. ### 15. Alexandria Tools
  832. Firecrawl Alexandria is a catalogue of data providers reachable through the Firecrawl API with a Firecrawl API key on a team with Alexandria access. Keyless sessions (hosted or local) get `Alexandria requires an API key on a team with Alexandria access`; Alexandria discovery tools are not listed for hosted keyless sessions. A stdio server pointed at its own API with `FIRECRAWL_API_URL` is the exception: it sends Alexandria tools to that API, which answers for the account.
  833. **Semantic discovery (`firecrawl_search`):**
  834. ```json
  835. {
  836. "name": "firecrawl_search",
  837. "arguments": {
  838. "query": "podcast conversations about AI agents",
  839. "sources": ["web", "alexandria"],
  840. "domainTools": true,
  841. "limit": 2
  842. }
  843. }
  844. ```
  845. `data.tools` defaults to compact suggestions with provider, capability, and
  846. description. Set `toolDetail: "summary"` for metadata and navigation, or
  847. `toolDetail: "full"` for contracts including inputs, response fields and examples. `domainTools: true` adds contextual matches to
  848. query mentions and result URLs in that same array. Check `warning` for unavailable
  849. discovery. Search requires a query and does not accept catalogue traversal filters.
  850. This discovery works on both the full and search-only MCP surfaces.
  851. **Explore the library (`alexandria_library_search`):** the catalogue is a read-only filesystem, and the tool runs one shell command over it.
  852. ```json
  853. {
  854. "name": "alexandria_library_search",
  855. "arguments": { "command": "grep -ril \"podcast\" /library | head -20" }
  856. }
  857. ```
  858. | Path | Holds |
  859. | --- | --- |
  860. | `/library/README.md` | Counts, the layout and every category |
  861. | `/library/<category>/README.md` | The category's providers |
  862. | `/library/<category>/<provider>/README.md` | The provider's capabilities |
  863. | `/library/<category>/<provider>/<capability>.md` | One contract: when to use it, inputs, outputs and the call that runs it |
  864. | `/examples/<provider>/<capability>.json` | A recorded response |
  865. A file path is the execute address: `/library/finance/fred/series/observations.md` is provider `fred`, capability `series/observations`. Typical commands:
  866. | Intent | Command |
  867. | --- | --- |
  868. | What is in the library | `cat /library/README.md` |
  869. | Which providers cover a topic | `grep -ril "mortgage" /library \| head -20` |
  870. | What a provider offers | `cat /library/finance/fred/README.md` |
  871. | One contract | `cat /library/finance/fred/series/observations.md` |
  872. | What a response looks like | `head -c 2000 /examples/fred/series/observations.json` |
  873. Commands are `ls`, `tree`, `cat`, `head`, `tail`, `grep`, `find`, `wc`, `sort`, `uniq`, `cut`, `tr`, `sed`, `jq` and `xargs`, with pipes. There is no network and the library cannot be written. The result is the command's output as text; `structuredContent` carries `stdout`, `stderr`, `exitCode`, and `truncated` when output was cut at 30,000 characters. A command that finds nothing is not an error: `grep` exits 1 and the text is `[no output; exit code 1]`. Library lookups cost zero credits and never run a provider. The files hold what the same account would see in discovery, without prices.
  874. This tool requires the Alexandria API deployment that serves `firecrawl/library`.
  875. **Execute (`alexandria_library_read`):** `calls` is an array of one to ten `{provider, capability, options}` entries, which may name different providers. `provider` and `capability` come from search results or a library path, and `options` follow the contract. `requestId` and `timeout` may also be supplied. Results come back in `data.alexandria` in the same order, and one call can fail while the others succeed.
  876. ```json
  877. {
  878. "name": "alexandria_library_read",
  879. "arguments": {
  880. "calls": [
  881. { "provider": "fred", "capability": "series/observations", "options": { "series_id": "CPIAUCSL" } },
  882. { "provider": "fred", "capability": "series/observations", "options": { "series_id": "MORTGAGE30US" } }
  883. ]
  884. }
  885. }
  886. ```
  887. One call sent as the arguments themselves (`{provider, capability, options}`) is read as a `calls` array of one.
  888. **Earlier tools (`firecrawl_find_tools`, and `firecrawl_scrape` with `alexandria`):** on the full surface (the default, where both new tools are listed), this server no longer lists `firecrawl_find_tools`, and `firecrawl_scrape` lists `url` only. Both still answer the calls they used to, so clients and prompts that learned them keep working; new ones should use `alexandria_library_search` and `alexandria_library_read`. `firecrawl_find_tools` browses the catalogue (`{}` for categories, then `categories`, `providers` and `capabilities` to narrow to one contract, or `query` and `urls` for lookup), and `firecrawl_scrape` takes `alexandria` in place of `url`, as one `{provider, capability, options}` call or an array of up to ten, with `requestId` and `timeout`.
  889. The search-only endpoint lists and documents the earlier tools, because its tool list is fixed by its connector listing. An embedder whose `toolFilter` leaves either new tool out gets the earlier tools too.
  890. **Returns:** `{ success, scrape_id, requestId, data: { alexandria: [...], creditsCost } }`. Each item is either a result (`provider`, `capability`, `data`, `records`, `upstreamStatus`) or an `error` with a `code`; a provider error is reported in its item, not as a failed call, and `data.creditsCost` is the total charged for the request. Alexandria error bodies (403 without Alexandria access, and 402/409 billing statuses) are relayed in-band with their `code`.
  891. Execution generates one `x-request-id` and returns it on success or failure. Retry
  892. the identical payload with that `requestId`; do not create a new ID after an
  893. uncertain outcome. Available credits are checked by the API.
  894. An Alexandria provider whose terms the team has not accepted fails before anything runs with
  895. HTTP 403 and this body:
  896. ```json
  897. {
  898. "success": false,
  899. "code": "THIRD_PARTY_DATA_TERMS_REQUIRED",
  900. "error": "An organization admin must accept the benzinga provider's terms (version 2026-09-12-placeholder) before this request can run. Accept them at https://www.firecrawl.dev/app/alexandria/benzinga",
  901. "requiresAction": {
  902. "type": "accept_terms",
  903. "terms": "benzinga",
  904. "version": "2026-09-12-placeholder",
  905. "url": "https://www.firecrawl.dev/app/alexandria/benzinga"
  906. }
  907. }
  908. ```
  909. The tool result relays it as an error with `structuredContent` carrying `code`,
  910. `status: 403`, `requestId`, the `requiresAction` object unchanged, and
  911. `next_actions` (`human_action_required` then `retry_same_request`). Accepting
  912. terms is a legal act, so an organization admin accepts them in the Firecrawl dashboard, not
  913. through MCP. Use the returned `nextTool` call to read the agreement: `alexandria_library_read`
  914. with `calls: [{provider: "firecrawl", capability: "terms/show", options: {provider: "<provider>"}}]`
  915. (on the search-only endpoint, the same call through `firecrawl_scrape` with `alexandria`),
  916. sent separately from provider execution, and present it to the user. An organization admin then
  917. accepts it at `requiresAction.url`, or at https://www.firecrawl.dev/app/settings?tab=data-sources.
  918. Both tools refuse every other `terms/*` capability, so they make no account changes. A request
  919. for data is not consent, and no automatic acceptance or uncertain retries occur.
  920. No credits are charged for the blocked retrieval. After the admin confirms acceptance, call the same
  921. tool again with the identical payload and `requestId`.
  922. ### 15b. Enrich Tools
  923. People and company search and enrichment over Alexandria's B2B data providers. Both tools are listed wherever the server has a credential: they are not listed in local keyless mode or to keyless sessions. The [search-only endpoint](#search-only-endpoint) includes them too. They need a Firecrawl credential (an API key or OAuth access) on a team with Alexandria access.
  924. | Tool | Use it for | Providers |
  925. | --- | --- | --- |
  926. | `people_company_search` | Finding people (`entity: "person"`) by title, seniority, function, employer and location, or companies (`entity: "company"`) by industry, headcount, location, technology, keywords or founding year | Firecrawl's search waterfall picks them |
  927. | `people_company_enrich` | Resolving known people to profiles, or known companies to firmographics. With `contact_fields`, finding work email, personal email or mobile for known people | chosen by Firecrawl's enrichment waterfall |
  928. #### people_company_search
  929. `people_company_search` takes one normalized input and sends it to Alexandria's search waterfall, `firecrawl/search/auto`, as a single request: `entity` (`"person"` or `"company"`, required), optional `query`, `filters` (`titles`, `seniority`, `functions`, `company_domains`, `locations`, `industries`, `technologies`, `keywords`, and `headcount` and `founded_year` as `{ "min", "max" }`), `limit` (1 to 100, default 10), `cursor`, `count_only` and `max_credits` (default 1000). For people, company filters describe the employer. The waterfall asks its providers one at a time in list-price order, and only those that apply every filter given; when none does, it searches companies first and then people at the domains it found, and a request no provider or chain covers is refused with `unsupported_filters`, naming the filter to drop. With `company_domains` it stops at the first provider that returns anyone; otherwise it fills `limit` across up to three providers, asking each only for the rows still missing, and drops duplicates. A row whose own title, employer domain, country or city, headcount or founding year fails a filter given, or whose title names another seniority level or function than those given (SVP, EVP and AVP meet `vp`), is dropped, and the search keeps filling from the next provider. Rows carry name, title (`title_match` is `current` or `past`), company, location, LinkedIn URL and `source`, and never emails or phones. A request that names one person is refused with `use_enrich` and pointed to `people_company_enrich`. `providers` lists each provider call with its status, rows, rows `dropped` for failing a filter, rows kept as `unverified` because their title names no level or function for a `seniority` or `functions` filter, credits and time. `provider` limits the call to one provider, and with `options` sends that provider's own search options as given.
  930. ```json
  931. {
  932. "name": "people_company_search",
  933. "arguments": { "entity": "person", "filters": { "titles": ["Head of Data"], "company_domains": ["example.com"] }, "limit": 10 }
  934. }
  935. ```
  936. #### people_company_enrich
  937. `people_company_enrich` takes records, not provider blocks, and runs Firecrawl's enrichment waterfall on them. `people` takes `name`, `first_name`, `last_name`, `company`, `domain`, `linkedin_url`, `email` and `phone`; each person needs a `linkedin_url`, `email` or `phone`, or a name with a `company` or `domain`. `companies` takes `domain`, `name` and a company `linkedin_url`, and each needs one of them. A call takes at most 10 records, people and companies together.
  938. Without `contact_fields` each person gets a profile and each company gets firmographics. `contact_fields` (`work_email`, `personal_email`, `mobile`) asks for those values for each person, together with the person's profile, found first so the contact lookups can use it (`profile: false` skips it); companies in the same call still get firmographics, and `contact_fields` with only companies fails with `invalid_input`. Mobile is opt-in: phone providers, the costliest lookups, run and bill only when `contact_fields` lists `mobile`.
  939. For each requested field, Firecrawl tries the providers that can use the record's inputs one at a time, ordered by listed price and past success rate, and stops at the first one that finds the field. A provider that has no match, errors or is rate limited is skipped for the next one, without retries. A person known only by an email or phone is first resolved to a profile, and the contact providers then use what it revealed.
  940. ```json
  941. {
  942. "name": "people_company_enrich",
  943. "arguments": {
  944. "contact_fields": ["work_email"],
  945. "people": [{ "name": "Jane Doe", "domain": "example.com" }, { "linkedin_url": "https://www.linkedin.com/in/janedoe" }],
  946. "companies": [{ "domain": "example.com" }]
  947. }
  948. }
  949. ```
  950. The response has `people` and `companies` lists with one entry per input, each with `input_index` and `results`: one `{ "provider", "data" }` entry per provider that found a requested field, where `data` is that provider's own response, unchanged. Each record also has `fields`: for each filled field, the `provider` behind it; for an email the chosen `value`, `verified` (the provider marked it deliverable) and `domain_match`; for a profile or firmographics `complete`, false when only a partial answer was found, and for firmographics `linkedin_confirmed`. A work email is never a free-mail or role address, and is on the company's domain when one is known; `verified_only: true` returns only verified emails. A record nothing was found for has empty `results`. `credits_used` is what the call charged: each provider that found something is charged its listed price, and misses are free. `max_credits` (at most 10,000) caps the call: a provider is tried only while its listed price still fits. Without it the call is uncapped. `stopped: "team_quota"` means the team ran out of credits during the call. To call one specific provider, use `firecrawl_scrape` with an `alexandria` body.
  951. Both tools also accept, and drop, the `conversationId` and `objective` fields agents carry between Firecrawl tools.
  952. ### 15c. Jobs Tool (`jobs_search`)
  953. `jobs_search` finds job postings and tells whether a posting is still open. It is listed wherever the enrich tools are, the [search-only endpoint](#search-only-endpoint) included, and needs the same credential. It sends its input as a single request to Alexandria's jobs route, `firecrawl/jobs/auto`, which picks the mode and the providers:
  954. | Input | What it does |
  955. | --- | --- |
  956. | `url`, or `urls` (up to 10) | Reads each posting and returns its status. One `url` also returns the description |
  957. | `company` (a name or domain) | Lists the company's open roles from its own job board; add `query` for one role there |
  958. | `query` (a title or keywords) | Searches postings by role, with `location`, `remote` and `posted_within_days`; `group_by: "employer"` groups them by employer, and `boards_only` searches employers' own boards only |
  959. At least one of `query`, `company`, `url` or `urls` is required. `max_credits` (default 200) and `include_description` apply to every mode. `limit` (1 to 100, default 10) applies to a search by `query` or `company`, and `cursor`, `provider`, `group_by` and `boards_only` to a search by `query` alone; a read by `url` or `urls` takes none of them.
  960. ```json
  961. {
  962. "name": "jobs_search",
  963. "arguments": { "query": "data engineer", "location": "Berlin", "posted_within_days": 14 }
  964. }
  965. ```
  966. Every row has the same fields: `title`, `company`, `company_domain`, `location`, `remote`, `employment_type`, `posted_at` (as the board states it), `url`, `apply_url`, `source`, `source_type` (`employer_board`, `employer_site`, `aggregator` or `index`), `board`, `status` and `checked_at`, plus `description`, `salary` and `requirements` where they apply, and `reason` on a posting that is `closed`, `not_found`, `error` or `unverified` after a read by URL. `status` is `open` when the posting was read from the employer's board or live posting page in this call, and `unverified` when it comes from a job site and was not confirmed on the employer's board; a posting checked by URL can also be `closed`, `not_found` or `error`.
  967. The response also carries `mode`, `count`, `next_cursor`, `providers` (each provider call with its `status`, the rows it `returned` and `dropped`, and its `credits`), `credits`, `credits_pending`, `stopped` and `notes`; `employers` with `group_by`; and, for a company, `boards` (the boards read and what each covers) and `resolution` (how the board was found). When no board is found for a company, the rows come from job sites and `notes` says so. Against a Firecrawl API that does not serve the route yet, the tool fails with `jobs_search_unavailable`.
  968. ### 16. Credit Usage Tool
  969. The tool requires an authenticated Firecrawl account and is read-only.
  970. - `firecrawl_credit_usage` defaults to `{ "view": "current" }` and returns `remainingCredits`, `planCredits`, `billingPeriodStart`, and `billingPeriodEnd`. Remaining credits can exceed plan credits when the team has top-ups or grants.
  971. - Pass `{ "view": "historical" }` for calendar-month periods containing `startDate`, `endDate`, and `creditsUsed`. Passing `{ "byApiKey": true }` also selects the historical view and splits periods by API key; each row then includes `apiKey`. Passing `{ "byEndpoint": true }` instead splits periods by the endpoint that used the credits (scrape, search, crawl, map, agent, ...); each row then includes `endpoint`. Pass `{ "bin": "day" }` for one period per UTC day instead of per calendar month. Do not combine `byApiKey` with `byEndpoint`, or any of these with `{ "view": "current" }`. The latest period's `endDate` can be null. If the Firecrawl API does not offer the endpoint split or daily periods yet, the result carries a `notice` and monthly figures.
  972. ## Programmatic use (unstable)
  973. The package also exposes a library entry point for embedding the server in another runtime. It is **unstable**: the API, its options and its types may change in any release, including minor and patch releases, so pin an exact version.
  974. ```sh
  975. npm install --save-exact firecrawl-mcp zod
  976. ```
  977. The example defines tool parameters with `zod`, so the embedding project installs it as its own dependency.
  978. ```js
  979. import { createFirecrawlMcpServer } from 'firecrawl-mcp/server';
  980. import { z } from 'zod';
  981. const server = createFirecrawlMcpServer({
  982. transport: 'httpStream',
  983. apiKey: process.env.FIRECRAWL_API_KEY,
  984. unstable_hooks: {
  985. registerExtraTools: (registrar) => {
  986. registrar.addTool({
  987. name: 'my_tool',
  988. description: 'An extra tool served next to the Firecrawl tools.',
  989. parameters: z.object({ text: z.string() }),
  990. execute: async ({ text }) => text,
  991. });
  992. },
  993. },
  994. });
  995. await server.start({
  996. transportType: 'httpStream',
  997. httpStream: { port: 3000, host: '127.0.0.1', endpoint: '/mcp', stateless: true },
  998. });
  999. // MCP endpoint: http://127.0.0.1:3000/mcp
  1000. ```
  1001. Set `host` explicitly. Without it the server listens on `localhost`, which Node binds to a single address (often only `::1`), so requests to `127.0.0.1` are refused. Use `0.0.0.0` or `::` to accept connections from other machines only behind network access controls or an `unstable_hooks.authenticate` check: without one, every caller that can reach the port is served with the configured `apiKey`.
  1002. The library doesn't check `Host` or `Origin` unless asked, and its CORS headers allow any origin. A server reachable from a browser on the same machine should pass `httpStream.allowedHosts` (for example `['localhost', '127.0.0.1', '[::1]']`): requests whose `Host` or `Origin` header names another host then get `403` (except `GET` and `HEAD` on the health path), and CORS headers echo the allowed origin. The command line sets this list in local HTTP mode.
  1003. Options mirror the CLI's environment variables: `apiUrl`, `apiKey`, `transport`, `logging`, `safeMode`, `fileAccess` (`local` or `upload`), `requireCredential`, `searchFeedback` and `endpointFeedback`. `unstable_hooks` accepts:
  1004. | Hook | Purpose |
  1005. |---|---|
  1006. | `authenticate(request)` | Resolve the session for a request; throw a `Response` to reject it. |
  1007. | `wrapTool(tool)` | Decorate every registered tool. |
  1008. | `onToolResult(event)` | Observe the start and outcome of each tool call. |
  1009. | `instructions` | Server instructions, or a function choosing from the defaults; it may return a function of the session to give each session its own. |
  1010. | `registerExtraTools(registrar, context)` | Add tools after the built-in ones. |
  1011. | `outboundRequest(session)` | Credential and extra headers for each Firecrawl API request. |
  1012. | `beforeKeylessRequest(session, origin)` | Refuse a keyless request by throwing. |
  1013. | `toolFilter(name)` | Leave built-in tools out of the instance. |
  1014. | `configureHttp(app)` | Add HTTP routes. |
  1015. | `oauth.protectedResource` | Serve OAuth protected-resource metadata. |
  1016. The server is built on the official MCP TypeScript SDK (`@modelcontextprotocol/server`). Use the types exported from `firecrawl-mcp/server` (`Session`, `ToolDefinition`, `ToolRegistrar`, `FirecrawlMcpServerHooks` and others) rather than the SDK's own.
  1017. The entry point also exports the helpers the built-in tools use, such as `recoveryPayload`, `normalizeHeader`, `requestOrigin`, `isRuntimeUserAgent`, `initializeClientSlug`, `searchToolBaseFields`, `searchOutputSchema` and `structuredCompact`, so extra tools and hooks can match the built-in behaviour. They are unstable as well.
  1018. ## Logging System
  1019. The server includes comprehensive logging:
  1020. - Operation status and progress
  1021. - Performance metrics
  1022. - Rate limit tracking
  1023. - Error conditions
  1024. Example log messages:
  1025. ```
  1026. [INFO] Firecrawl MCP Server initialized successfully
  1027. [INFO] Starting scrape for URL: https://example.com
  1028. [ERROR] Rate limit exceeded
  1029. ```
  1030. ## Error Handling
  1031. The server provides robust error handling:
  1032. - API rate-limit errors surfaced to the MCP client
  1033. - Detailed error messages
  1034. - Network resilience
  1035. Example error response:
  1036. ```json
  1037. {
  1038. "content": [
  1039. {
  1040. "type": "text",
  1041. "text": "Error: Rate limit exceeded"
  1042. }
  1043. ],
  1044. "isError": true
  1045. }
  1046. ```
  1047. ## Development
  1048. ```bash
  1049. # Install dependencies
  1050. npm install
  1051. # Build
  1052. npm run build
  1053. # Run tests
  1054. npm test
  1055. ```
  1056. ### Contributing
  1057. 1. Fork the repository
  1058. 2. Create your feature branch
  1059. 3. Run tests: `npm test`
  1060. 4. Submit a pull request
  1061. ### Thanks to contributors
  1062. Thanks to [@vrknetha](https://github.com/vrknetha), [@cawstudios](https://caw.tech) for the initial implementation!
  1063. Thanks to MCP.so and Klavis AI for hosting and [@gstarwd](https://github.com/gstarwd), [@xiangkaiz](https://github.com/xiangkaiz) and [@zihaolin96](https://github.com/zihaolin96) for integrating our server.
  1064. ## License
  1065. MIT License - see LICENSE file for details
  1066. ### Structured data and large results
  1067. Authenticated search defaults to web results, semantic Alexandria tools, and domain matches. Start with the actual question. Use `alexandria_library_search` to check whether a provider covers the data and to read a selected contract: the library README, a category, a provider, then one capability file. Run capabilities through `alexandria_library_read`; URL scraping and search never execute provider tools. The search-only endpoint has `firecrawl_find_tools` and `firecrawl_scrape` with `alexandria` for these two steps.
  1068. Read the recorded example under `/examples` only if the input or output shape is unclear. Inspect related capabilities together, for example `cat` two contracts in one command, and reuse what you read.
  1069. For a potentially large workflow result, supply and preserve a top-level `requestId` before execution. That ID remains available even if the client rejects the response. Regular URL scrapes use the returned scrape ID instead.
  1070. For a large retained workflow or regular scrape result, call `alexandria_library_read` with:
  1071. ```json
  1072. {
  1073. "calls": [
  1074. {
  1075. "provider": "firecrawl",
  1076. "capability": "bash",
  1077. "options": {
  1078. "requestId": "<source-request-or-scrape-id>",
  1079. "command": "ls -lh"
  1080. }
  1081. }
  1082. ]
  1083. }
  1084. ```
  1085. Read `stdout`, `stderr`, `exitCode`, and `workspaceId` in `data.alexandria[0].data`. Continue with `options: {workspaceId, command}` to inspect `response.json` using `jq`, or `document.md` using bounded text commands for regular scrapes. Keep output selective. Source loading must be a standalone call; its nested source ID differs from the top-level execution request ID. Workspaces expire after five idle minutes, and not every result is retained (including ZDR and API-provider workflow payloads). Search IDs are not supported.
  1086. For workflow sources, `response.json` preserves the API envelope: select `.data.alexandria[].data`, then the selected contract’s `response.key` when nonempty. Combine related counts and projections in one Bash command when that shape is known, rather than repeatedly inspecting keys.
  1087. Successful Alexandria execution responses above 20,000 estimated tokens (serialized UTF-8 bytes divided by four) return a small handoff after remote Bash confirms the complete batch is accessible. Follow `nextTool` to inspect the retained data. This adds one Bash call and starts a workspace with a five-minute idle TTL. The full payload is preserved. If confirmation fails, the original response stays inline. Search, ordinary URL scrape, error responses and Firecrawl utility calls are unchanged. This delivery budget does not measure the client’s remaining context; no process-local result cache is added. When local filesystem tools are available, saving CLI output and reading selected sections is another option.
  1088. The CLI discovery sequence maps to these MCP calls:
  1089. | Intent | Tool | Arguments |
  1090. | --- | --- | --- |
  1091. | Web + semantic + domain tools | `firecrawl_search` | `{"query":"<user question>"}` |
  1092. | Semantic tools only | `firecrawl_search` | `{"query":"<user question>","sources":["alexandria"]}` |
  1093. | Categories | `alexandria_library_search` | `{"command":"cat /library/README.md"}` |
  1094. | Providers in a category | `alexandria_library_search` | `{"command":"cat /library/<category-id>/README.md"}` |
  1095. | A provider's capabilities | `alexandria_library_search` | `{"command":"cat /library/*/<provider-id>/README.md"}` |
  1096. | Selected contract | `alexandria_library_search` | `{"command":"cat /library/*/<provider-id>/<capability-id>.md"}` |
  1097. | Execute | `alexandria_library_read` | `{"calls":[{"provider":"<provider-id>","capability":"<capability-id>","options":{"<required-field>":"<value>"}}]}` |
  1098. The search surface keeps `firecrawl_find_tools` and `firecrawl_scrape` with `alexandria` for the last five rows. Reuse a complete contract from search when present rather than making another lookup.
  1099. ### Alexandria session feedback
  1100. The existing `firecrawl_feedback` tool accepts `endpoint: "alexandria"`:
  1101. ```json
  1102. {
  1103. "endpoint": "alexandria",
  1104. "rating": "partial",
  1105. "requestedWebsite": {
  1106. "url": "https://example.com",
  1107. "requestedFunctionality": "Find records and download their attachments"
  1108. },
  1109. "objective": "Compare contract requirements across agencies before bidding",
  1110. "rationale": "Found summaries but could not retrieve attachments"
  1111. }
  1112. ```
  1113. The optional `objective` is the underlying goal of the session: what the agent or its user was ultimately trying to accomplish, beyond the single website in `requestedWebsite`.
  1114. This uses authenticated `POST /v2/feedback`, without a job ID. It must arrive within 20 minutes of the team's most recent Alexandria search, discovery, or execution; later feedback is rejected with `FEEDBACK_WINDOW_EXPIRED`. Eligible feedback can refund 1 credit, subject to daily caps of 10 credits per website and 100 credits per team (UTC day). Past either cap, feedback is still recorded with no refund, and the response sets `websiteCapReached` or `dailyCapReached`. Optional `providerFeedback` and `capabilityFeedback` arrays describe coverage gaps and execution issues; the tool schema lists supported issue values. A `new_capability_request` requires `requestedFunctionality`; `missing_capability` (the provider exists but lacks the capability) does not. Existing feedback opt-out and authentication controls apply.
  1115. #### Per-call feedback tokens
  1116. Alexandria provider call results can carry a `feedbackToken` so ratings are attributed to the calls they are about. The server keeps each token per MCP session (keyed by the `Mcp-Session-Id` and the caller's credential, or by the credential alone when the client sends no session id; at most 20 tokens, dropped after 24 hours) and shows the agent a short `feedbackRef` such as `c3` in its place, so long tokens never reach the model. `firecrawl_feedback` sends the session's tokens with every Alexandria rating, so the overall `rating` covers every retained tokenized call in the session, and accepts an optional `callRatings` array to rate individual calls by their ref:
  1117. ```json
  1118. {
  1119. "endpoint": "alexandria",
  1120. "rating": "partial",
  1121. "requestedWebsite": { "url": "https://example.com", "requestedFunctionality": "Find records" },
  1122. "rationale": "The search call worked, the detail call failed",
  1123. "callRatings": [
  1124. { "ref": "c1", "rating": "good" },
  1125. { "ref": "c2", "rating": "bad" }
  1126. ]
  1127. }
  1128. ```
  1129. Refs that are unknown or expired are ignored, and the result says so in `note`. A successful submission clears the tokens it sent, so the next rating covers only new calls. Results that carry no token (for example under zero data retention) keep working as before.
  1130. Eligible Alexandria execution and discovery results include a `feedbackTool` pointer with the tool name and a skeleton of the arguments. The pointer is omitted for Firecrawl-internal calls such as `bash` and when `firecrawl_feedback` is not registered (`FIRECRAWL_NO_ENDPOINT_FEEDBACK` or keyless startup).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.