Firecrawl Agent

You run the Firecrawl Agent MCP Server to enable AI-powered web data extraction and research via the Firecrawl Agent API. This server lets you run an autonomous AI agent, perform web searches, scrape single pages, and obtain structured outputs while controlling costs and managing long-running tasks.

How to use

Use this MCP server with an MCP client to perform AI-driven data extraction and research tasks. You can start an agent job to search and navigate websites, or execute a single scrape or search, receiving structured JSON outputs that conform to your specified schema. When you need quick results, use a synchronous execution. For longer tasks, start an asynchronous job and poll for completion. You can control spending with a maximum credits limit per task.

How to install

Prerequisites: Node.js installed on your system. You will clone the project folder, install dependencies, configure your API key, and build the server.

# Navigate to the project folder
cd firecrawl-agent-mcp

# Install dependencies
npm install

# Prepare environment with your API key
cp .env.example .env
# Edit .env to add your FIRECRAWL_API_KEY
# FIRECRAWL_API_KEY=fc-YOUR_API_KEY_HERE

# Build the server for deployment
npm run build

Additional setup and notes

Configure the MCP server in your Claude Code configuration in one of the following ways.

{
  "mcpServers": {
    "firecrawl-agent": {
      "command": "node",
      "args": ["/absolute/path/to/firecrawl-agent-mcp/dist/server.js"],
      "env": {
        "FIRECRAWL_API_KEY": "fc-YOUR_API_KEY_HERE"
      }
    }
  }
}

{
  "mcpServers": {
    "firecrawl-agent": {
      "command": "node",
      "args": ["./firecrawl-agent-mcp/dist/server.js"],
      "env": {
        "FIRECRAWL_API_KEY": "fc-YOUR_API_KEY_HERE"
      }
    }
  }
}

Cost and usage patterns

The Firecrawl Agent uses dynamic billing based on task complexity. Simple extractions cost fewer credits, while complex research tasks cost more. You can set a maximum credit limit to prevent overspending.

Development

Development and testing commands you might run locally include a watch mode for rapid iteration, starting the server directly, and using an SSE transport mode for HTTP-based communication.

# Watch mode during development
npm run dev

# Run the server directly
npm start

# SSE transport mode for HTTP-based communication
npm run start:sse

Troubleshooting

Common issues and fixes include API key problems, unauthorized access, rate limits, and ensuring the server is built and correctly configured.

FIRECRAWL_API_KEY environment variable is required. Ensure a .env file exists or the variable is set in your MCP host configuration.
HTTP 401: Unauthorized — your API key is invalid. Obtain a new one from Firecrawl.
HTTP 429: Too Many Requests — you’ve hit rate limits. Wait and retry or upgrade your plan.
Tools not showing up — ensure the server is built and the MCP path is correct, then restart your MCP client.

Notes on security and configuration

Keep your API key secure. Only expose FIRECRAWL_API_KEY to trusted environments. Use environment variable management practices and avoid embedding secrets in code or commit history.

Examples of usage patterns

Use synchronous execution for immediate results, asynchronous execution for long-running research, and the scrape feature to extract content from a specific URL without using AI agents.

Available tools

agent_execute

Execute the AI agent synchronously and wait for completion. Provide a prompt describing what data to extract, optional URLs to search, a JSON schema for structured output, and an optional maxCredits limit.

agent_start

Start an asynchronous agent job that runs in the background. Receive a jobId to poll status later.

agent_status

Poll the status of an asynchronous agent job using the provided jobId. Returns progress and results when finished.

scrape

Scrape content from a single URL without AI agent capabilities. Supports output formats like markdown, html, rawHtml, links, or screenshot.

search

Search the web and scrape multiple results according to a query and optional formats.