Firecrawl MCP Server Cursor IDE Setup (2026): Hosted, OAuth, API Key and Local

How do you set up the Firecrawl MCP server in Cursor? Add a firecrawl entry to ~/.cursor/mcp.json that points at Firecrawl's hosted endpoint. The fastest version is one line, "url": "https://mcp.firecrawl.dev/v2/mcp", which works with no account at all but only exposes three tools (scrape, search and parse). For the full tool set, either switch the URL to https://mcp.firecrawl.dev/v2/mcp-oauth and sign in through the browser, or keep /v2/mcp and send your API key as an Authorization: Bearer header. If you need the server running on your own machine, npx -y firecrawl-mcp with FIRECRAWL_API_KEY in the env block does that over stdio.

Everything below was checked on October 30, 2026 against Firecrawl's MCP documentation at docs.firecrawl.dev/mcp-server, its "Run Firecrawl MCP locally" page, the firecrawl/firecrawl-mcp-server README on GitHub, and Cursor's MCP documentation. Firecrawl changes its tool surface often, so where a detail is likely to move, this guide says so instead of pretending it is fixed.

What Firecrawl Adds That Other Web Servers Don't

This site already covers a few ways to put the web in front of a model, and they overlap less than their names suggest. The Fetch MCP server pulls a single URL and converts it to markdown, which is enough for static documentation pages. Playwright drives a real browser you control step by step. Search servers like Exa find pages but are not built to extract structured data from them.

Firecrawl sits across all three jobs. According to its README, the server can search the web (optionally pulling full page content for each result), scrape a known page into markdown or into JSON that matches a schema you supply, map the URLs on a site, crawl a section of a site with limits, parse PDFs and office documents, click and type on pages that need interaction before content appears, run asynchronous research "agent" jobs, monitor pages for changes, and report your credit usage. The scraping runs on Firecrawl's infrastructure rather than on your laptop, which is the main reason people reach for it over a local fetch: JavaScript-heavy pages render before extraction, and you are not managing a headless browser yourself.

The trade-off is that it is a hosted service with credits, rate limits and paid plans. Check Firecrawl's current billing and rate-limit pages before planning around a specific volume; this guide does not quote numbers because they change.

Pick a Connection Mode First

Firecrawl's docs describe keyless access, browser sign-in, and API keys for the hosted server, plus a local mode. They expose different tools. Choosing the wrong one is the most common reason someone "installs Firecrawl" and then cannot find the crawl tool.

Firecrawl's Get Started page puts it simply: signing in and adding an API key are two paths to the same access. Both reach the full tool surface on your team's plan.

A quick rule: try keyless if you only want to see whether Firecrawl's scraping beats what you have. Use OAuth for day-to-day interactive work in Cursor. Use an API key when there is no human around to click through a browser sign-in, such as a shared dev container or CI job. Run it locally when you have a self-hosted Firecrawl instance or a policy that requires MCP servers to run as local processes.

Where the Config Lives in Cursor

Cursor reads MCP servers from two files. ~/.cursor/mcp.json in your home directory makes a server available in every project. .cursor/mcp.json in a project root scopes it to that repo, which is how you share a setup with teammates through version control. Current Cursor builds manage installed servers from the Customize page in the sidebar, where you can also toggle a server off without deleting it. Editing the JSON file directly works the same way and is easier to review.

Never commit a project-level mcp.json that contains a literal API key. The OAuth and environment-variable patterns below avoid that.

Option 1: Keyless Hosted (No Account)

Add this to ~/.cursor/mcp.json (or the project file):

{
  "mcpServers": {
    "firecrawl": {
      "url": "https://mcp.firecrawl.dev/v2/mcp"
    }
  }
}

Save, then reload Cursor or toggle the server off and on. The firecrawl server should show as connected with three tools. Firecrawl documents this tier as rate-limited with daily limits, and its README states that tools such as crawl, map and agent still need a key. It exists for trying the service, not for running a crawl.

Option 2: Hosted With Browser Sign-In (OAuth)

Change only the URL:

{
  "mcpServers": {
    "firecrawl": {
      "url": "https://mcp.firecrawl.dev/v2/mcp-oauth"
    }
  }
}

Firecrawl's own example also includes "type": "http"; Cursor infers the transport from url, so either form works. Cursor supports OAuth for remote MCP servers using the authorization code flow with PKCE, so after you save, it starts the sign-in: a browser window opens, you log in to Firecrawl, and you approve a team. Firecrawl's docs are explicit that this URL is an MCP endpoint, not a web page. Opening it directly in a browser will not sign you in; let Cursor start the flow.

Three details worth knowing:

Rolling this out across a team? Shared configs, secret handling, and deciding which scraping tools an agent should be allowed to call automatically are the parts that take time. Talk to us if you want help wiring Firecrawl or other MCP servers into your stack.

Option 3: Hosted With an API Key

Create a key in the Firecrawl dashboard (firecrawl.dev/app/api-keys). Keep the plain /v2/mcp URL and pass the key as a bearer token:

{
  "mcpServers": {
    "firecrawl": {
      "url": "https://mcp.firecrawl.dev/v2/mcp",
      "headers": {
        "Authorization": "Bearer ${env:FIRECRAWL_API_KEY}"
      }
    }
  }
}

The ${env:FIRECRAWL_API_KEY} syntax is Cursor's config interpolation. Cursor resolves variables inside command, args, env, url, and headers, so the key lives in your shell profile or system environment instead of in a JSON file that might end up in a repo. Remote servers do not support Cursor's envFile option (that is stdio-only), which is why interpolation is the right tool here. Set the variable before launching Cursor:

export FIRECRAWL_API_KEY=fc-your-key-here

On macOS, apps launched from the Dock do not always see variables set in .zshrc. If the server fails to authenticate, start Cursor from a terminal where the variable is set, or put the literal key in the global ~/.cursor/mcp.json (never the project one).

Firecrawl's README is blunt about two things here: never put an API key in the server URL, and never paste one into an agent chat. Older community guides show a URL with the key embedded in the path. Use the header form instead.

Optional: an HTTP integration can name itself with an X-Firecrawl-Origin header (for example X-Firecrawl-Origin: cursor-backend-team). Per the README, that only changes the origin label Firecrawl records for requests, which can make usage easier to attribute when several teams share an account. Tool results are unaffected.

Option 4: Run the Server Locally With npx

Local mode is the original way the server shipped and is still documented. Firecrawl's local-setup page requires Node.js 22 or newer. Check with node --version.

{
  "mcpServers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp@3.33.2"],
      "env": {
        "FIRECRAWL_API_KEY": "${env:FIRECRAWL_API_KEY}"
      }
    }
  }
}

The version above is the reviewed release Firecrawl's local page pins in its examples as of this update. Pinning a version in args is a good habit for any MCP server that runs code on your machine, because a bare npx -y firecrawl-mcp pulls whatever is newest each time it starts. Bump the pin deliberately after reading the changelog.

Three environment variables matter in local mode:

In local HTTP mode the server, by default, only answers requests addressed to localhost, 127.0.0.1 or [::1], and rejects other Host or Origin headers with a 403. The README explains why: it stops web pages you visit from calling your local server through DNS rebinding and spending your API key. If you put it behind a reverse proxy or on a LAN address, list that name in FIRECRAWL_MCP_ALLOWED_HOSTS rather than turning the check off.

A Docker image (ghcr.io/firecrawl/firecrawl-mcp-server) runs the same server if you prefer containers. The README's stdio example passes the key with -e FIRECRAWL_API_KEY, and recommends pinning a sha- tag or digest when you need a fixed image, because version tags move.

Confirm It's Working

Open Customize and check that firecrawl is enabled and lists tools. Then, in Agent chat:

Use Firecrawl to scrape https://docs.firecrawl.dev/mcp-server and summarize the connection options it lists.

If the agent calls firecrawl_scrape and returns the page content, the connection works. Cursor asks for approval before running MCP tools by default; expand the arguments in the approval prompt the first few times so you can see what the agent is sending. On a keyless connection, ask for a crawl and you should see it is unavailable, which is expected rather than a fault.

The Tools, and When the Agent Should Use Each

Firecrawl's README says the server lists 27 tools on the full profile with default settings. You do not need most of them in a coding session. These are the ones that matter for development work:

The full profile also includes page monitors (firecrawl_monitor_*), research-paper tools, a US government-sources search, and feedback tools. They are real, but rarely what a coding agent needs.

If your Cursor setup is close to a tool-count ceiling, you have two levers. The hosted search-only endpoint (https://mcp.firecrawl.dev/v2/mcp-search) exposes a fixed set of nine tools, and its search does not fetch page content. In local mode, setting FIRECRAWL_NO_SEARCH_FEEDBACK=1 and FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 removes the two feedback tools. You can also disable individual tools from Customize.

Practical Prompts for Coding Work

Pull current API docs into context

Use firecrawl_map on https://docs.example.com to find the pages about webhooks, then scrape only those pages and summarize the signature verification steps.

Mapping first and scraping selectively uses far fewer credits than crawling a whole docs site.

Extract structured data for a test fixture

Scrape https://example.com/pricing as JSON with fields plan_name, monthly_price, and included_seats, and write the result to fixtures/pricing.json.

Check a library issue before debugging for an hour

Use firecrawl_developer_search to find GitHub issues or merged PRs about "hydration mismatch" in the version of Next.js in our package.json.

Read a PDF spec

Parse the PDF at https://example.com/spec.pdf and list every required field in the request schema.

Keep a crawl on a short leash

Crawl https://docs.example.com/api/* with limit 25 and maxDiscoveryDepth 2, then list endpoints that accept a cursor parameter.

Firecrawl or a Simpler Server?

Firecrawl is not always the right answer. If every page you need is static HTML and you already know the URLs, the Fetch server does the job with no account and no credits. If you need to log in, keep a browser session open across many of your own steps, and decide what to click next based on what you see, a browser-automation server is the better fit; Firecrawl's README itself says that each firecrawl_interact call runs one prompt or code turn to completion and returns control, so you cannot drive it step by step inside a single call. Firecrawl earns its place when you need search plus extraction in one place, schema-shaped JSON from messy pages, document parsing, or JavaScript-rendered content without running Chromium yourself.

Troubleshooting

Only three tools show up. You are on the keyless connection. Switch the URL to /v2/mcp-oauth, or add the Authorization header with an API key.

Opening the OAuth URL in a browser shows an error. Expected. It is a server URL for the MCP client. Remove and re-add the server in Cursor so Cursor starts the sign-in.

401 or authentication errors with an API key. Check the header value is exactly Bearer followed by the key, that the environment variable is visible to the Cursor process, and that the key has not been revoked in the dashboard. Firecrawl also issues OAuth access tokens (fco_…); refresh tokens (fcr_…) cannot be used as a bearer credential.

spawn npx ENOENT in local mode. Cursor cannot find npx. Install Node.js 22+, make sure npx is on the PATH Cursor sees, and fully restart Cursor. On Windows, Firecrawl's docs suggest running where npx and pointing the config at the returned npx.cmd path.

Local HTTP mode will not connect. Confirm HTTP_STREAMABLE_SERVER=true is set, hit http://localhost:3000/health, and use /mcp rather than /v2/mcp in the Cursor URL. A 403 from a non-localhost address means you need FIRECRAWL_MCP_ALLOWED_HOSTS.

A crawl returns far more than expected or burns credits. Put limit and path filters in the prompt explicitly. Agents tend to crawl broadly unless told not to. firecrawl_credit_usage shows where credits went.

Tools still missing after config changes. Check Cursor's MCP logs: open the Output panel (Cmd+Shift+U on macOS) and select "MCP Logs". Connection and auth errors appear there before they reach chat.

Security Notes

Scraped pages are untrusted input. A page can contain text written to steer an AI agent, and Firecrawl returns that text faithfully. Keep Cursor's tool-approval prompts on for tools that write files or run commands, so a scraped instruction cannot quietly trigger an action. Treat the API key like any other credential: environment variables or a secrets manager, a separate key per machine or integration, and revocation when a device is retired. Firecrawl's enterprise docs also describe per-key restrictions and IP allowlists if you need to lock a key down further. For a wider look at how servers authenticate and where keys should live, see our guide to MCP authentication with OAuth and API keys, and the Cursor MCP setup guide for general config patterns.

Frequently Asked Questions

Q: Is the Firecrawl MCP server free?
A: There is a keyless hosted tier that needs no account and exposes search, scrape, and parse within daily rate limits. The full tool set requires signing in or an API key, and usage then counts against your Firecrawl plan. Check Firecrawl's billing and rate-limit pages for current numbers.

Q: Which URL should I use in Cursor, /v2/mcp or /v2/mcp-oauth?
A: Use /v2/mcp-oauth if you want to sign in through the browser. Use /v2/mcp either with no credentials (keyless, three tools) or with an Authorization: Bearer header carrying your API key.

Q: Do I still need npx firecrawl-mcp?
A: Not for most Cursor users, since the hosted endpoint works without installing anything. Local mode remains useful for self-hosted Firecrawl instances, local-only policies, or when you want to pin and audit the exact server version.

Q: How is Firecrawl different from the Fetch MCP server?
A: Fetch converts a single URL to markdown from your machine. Firecrawl adds search, site mapping, bounded crawls, schema-based JSON extraction, document parsing, and page interaction, all run on Firecrawl's infrastructure.

Q: Can I point the MCP server at a self-hosted Firecrawl?
A: Yes. In local mode, set FIRECRAWL_API_URL to your instance's URL. The API key is optional if your instance does not require authentication.

Related Guides

Sources: Firecrawl MCP docs, Firecrawl MCP: run locally, firecrawl/firecrawl-mcp-server on GitHub, Cursor MCP documentation.