Firecrawl Agent MCP Server

A Model Context Protocol (MCP) server that provides AI-powered web data extraction and research capabilities through Firecrawl's Agent API.

Features

🤖 AI Agent Mode: Let the agent autonomously search, navigate, and gather data from complex websites 🔍 Web Search: Search and scrape multiple results at once 📄 Single Page Scraping: Extract content from specific URLs 📊 Structured Data: Define JSON schemas for type-safe data extraction 💰 Cost Control: Set maximum credit limits per request ⚡ Async Jobs: Start long-running tasks and poll for results

What is Firecrawl Agent?

Firecrawl Agent is a magic API that:

• No URLs Required: Just describe what you need via prompt

• Autonomous Navigation: Searches and navigates deep into sites to find your data

• Parallel Processing: Processes multiple sources simultaneously for faster results

• Structured Output: Returns data in your specified JSON schema format

Perfect for:

• Research tasks across multiple websites

• Extracting structured data (company info, pricing, contacts)

• Finding hard-to-reach information

• Competitive analysis and market research

Installation

1. Clone or Copy Files

2. Install Dependencies

3. Configure API Key

Copy the example environment file and add your Firecrawl API key:

Edit .env and add your API key:

Get your API key from: https://www.firecrawl.dev/

4. Build the Server

Configuration in Claude Code

Add the Firecrawl Agent MCP server to your Claude Code configuration:

Option 1: Edit .claude/settings.json

Option 2: Use .mcp.json in Project Root

Available Tools

agent_execute

Execute the AI agent synchronously (waits for completion).

Use when: You need immediate results for research tasks.

Parameters:

• prompt (required): Describe what data you want to extract

• urls (optional): Specific URLs to search (otherwise searches web)

• schema (optional): JSON schema for structured output

• maxCredits (optional): Maximum credits to spend

Example:

agent_start

Start an agent job asynchronously (returns job ID immediately).

Use when: You have long-running research tasks and want to poll for results.

Parameters: Same as agent_execute

Returns: Job ID to use with agent_status

agent_status

Check the status of an asynchronous agent job.

Parameters:

• jobId (required): Job ID from agent_start

Returns: Current status, progress, and results if completed

scrape

Scrape a single URL without AI agent capabilities.

Use when: You just need to extract content from one specific page.

Parameters:

• url (required): URL to scrape

• formats (optional): Output formats (markdown, html, rawHtml, links, screenshot)

• onlyMainContent (optional): Extract only main content (default: true)

• includeTags (optional): HTML tags to include

• excludeTags (optional): HTML tags to exclude

• waitFor (optional): Wait time for JS rendering (ms)

• timeout (optional): Request timeout (ms)

search

Search the web and scrape multiple results.

Use when: You want to find and extract data from multiple sources at once.

Parameters:

• query (required): Search query

• limit (optional): Maximum number of results (default: 5)

• formats (optional): Output formats for each result

Usage Examples

Example 1: Research Company Information

Example 2: Extract Pricing Information

Example 3: Competitive Analysis

Example 4: Long-Running Research

Cost Management

Firecrawl Agent uses dynamic billing based on task complexity:

• Simple extractions: Fewer credits

• Complex research: More credits

Control costs using:

Development

Watch Mode

Run Directly

SSE Transport Mode

For HTTP-based communication:

Troubleshooting

"FIRECRAWL_API_KEY environment variable is required"

Make sure you've:

1. Created a .env file with your API key

2. Or configured the env variable in your Claude Code settings

"HTTP 401: Unauthorized"

Your API key is invalid. Get a new one from https://www.firecrawl.dev/

"HTTP 429: Too Many Requests"

You've hit rate limits. Wait a moment and try again, or upgrade your Firecrawl plan.

Tools not showing up in Claude Code

1. Make sure you've built the server: npm run build

2. Check that the path in your MCP configuration is correct

3. Restart Claude Code after configuration changes

Learn More

• Firecrawl Agent Documentation

• Firecrawl API Reference

• MCP Protocol Specification

• Introducing Firecrawl Agent Blog Post

License

MIT

Support

For issues with:

• This MCP server: Open an issue in this repository

• Firecrawl API: Contact Firecrawl support

• Claude Code: Visit https://github.com/anthropics/claude-code

Built with ❤️ using the Model Context Protocol