# MCP Firecrawl

[![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript)](https://www.typescriptlang.org)
[![MCP](https://img.shields.io/badge/MCP-Server-000?logo=modelcontextprotocol)](https://modelcontextprotocol.io)
[![Firecrawl](https://img.shields.io/badge/Firecrawl-API-FF6B35)](https://www.firecrawl.dev)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A production-ready **Model Context Protocol (MCP)** server that integrates with the **Firecrawl API** to give AI assistants the power to **scrape**, **crawl**, and **search** the web.

> Works with **Claude Desktop**, **Cursor**, **VS Code (Cline/Roo Code)**, **Continue**, **OpenAI Agents SDK**, and any other MCP-compatible AI tool.

---

## Features

| Tool | Description | Input |
|------|-------------|-------|
| `scrape_url` | Scrape any webpage → returns clean Markdown content + metadata | `{ "url": "https://..." }` |
| `crawl_website` | Crawl multiple pages (up to 100) from a website | `{ "url": "https://...", "limit": 10 }` |
| `search_web` | Search the web using Firecrawl's search engine | `{ "query": "latest AI news" }` |

---

## Quick Start

```bash
# 1. Clone
git clone https://github.com/YOUR_USERNAME/MCP.git
cd MCP

# 2. Install
npm install

# 3. Configure
cp .env.example .env
# Edit .env → add your Firecrawl API key:
# FIRECRAWL_API_KEY=fc-your-key-here

# 4. Build & Run
npm run build
npm start
```

✅ Server is now running on **stdio** (default mode).

---

## Usage

### Command Line Test

```bash
# List available tools
node test-mcp.mjs tools

# Scrape a website
node test-mcp.mjs scrape https://example.com

# Search the web
node test-mcp.mjs search "latest TypeScript news"
```

### With OpenAI Agents SDK (TypeScript)

```typescript
import { Agent, run, MCPServerStdio } from "@openai/agents";

const mcp = new MCPServerStdio({
  name: "Firecrawl",
  fullCommand: "node dist/server.js",
  env: { FIRECRAWL_API_KEY: "fc-..." },
});

await mcp.connect();

const agent = new Agent({
  name: "Web Assistant",
  instructions: "Use tools to scrape, crawl, and search the web.",
  mcpServers: [mcp],
});

const result = await run(agent, "Scrape https://example.com");
console.log(result.finalOutput);
await mcp.close();
```

---

## Integration with AI Tools

### Claude Desktop

Add to `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "firecrawl": {
      "command": "node",
      "args": ["C:/path/to/MCP/dist/server.js"],
      "env": {
        "FIRECRAWL_API_KEY": "fc-..."
      }
    }
  }
}
```

### Cursor

Settings → Features → MCP → Add Server:

```
Name: firecrawl
Type: command
Command: node "C:/path/to/MCP/dist/server.js"
Environment: FIRECRAWL_API_KEY=fc-...
```

### VS Code + Cline / Roo Code

File: `.vscode/cline_mcp_settings.json`

```json
{
  "mcpServers": {
    "firecrawl": {
      "command": "node",
      "args": ["C:/path/to/MCP/dist/server.js"],
      "env": { "FIRECRAWL_API_KEY": "fc-..." },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### Continue (VS Code / JetBrains)

File: `~/.continue/config.json`

```json
{
  "experimental": {
    "mcpServers": {
      "firecrawl": {
        "command": "node",
        "args": ["C:/path/to/MCP/dist/server.js"],
        "env": { "FIRECRAWL_API_KEY": "fc-..." }
      }
    }
  }
}
```

### opencode

File: `./opencode.json`

```json
{
  "mcp": {
    "firecrawl": {
      "type": "local",
      "command": ["node", "MCP/dist/server.js"],
      "enabled": true,
      "env": { "FIRECRAWL_API_KEY": "fc-..." }
    }
  }
}
```

---

## HTTP Mode (Streamable HTTP)

Can't use stdio? Run the server as an HTTP endpoint instead:

```bash
npm run start:http
# Listening on http://127.0.0.1:3001/mcp
```

Then connect any MCP client to that URL.

---

## Project Structure

```
MCP/
├── src/
│   ├── server.ts              # Entry point (stdio + HTTP modes)
│   ├── tools/
│   │   ├── scrape.ts          # scrape_url tool
│   │   ├── crawl.ts           # crawl_website tool
│   │   └── search.ts          # search_web tool
│   ├── services/
│   │   └── firecrawl.ts       # FirecrawlApp API wrapper
│   └── types/
│       └── index.ts           # TypeScript interfaces
├── test-mcp.mjs               # CLI test utility
├── .env.example               # Environment template
├── package.json
├── tsconfig.json
└── README.md
```

---

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `FIRECRAWL_API_KEY` | ✅ Yes | — | Your [Firecrawl](https://www.firecrawl.dev) API key |
| `HTTP_HOST` | ❌ No | `127.0.0.1` | HTTP bind address (HTTP mode only) |
| `HTTP_PORT` | ❌ No | `3001` | HTTP port (HTTP mode only) |

---

## NPM Scripts

| Script | Description |
|--------|-------------|
| `npm run build` | Compile TypeScript → `dist/` |
| `npm start` | Run in stdio mode |
| `npm run start:http` | Run in HTTP mode |
| `npm run dev` | Run with hot-reload (stdio) |
| `npm run dev:http` | Run with hot-reload (HTTP) |
| `npm run clean` | Delete `dist/` |

---

## Tech Stack

- **Runtime:** Node.js 18+
- **Language:** TypeScript
- **MCP SDK:** `@modelcontextprotocol/sdk`
- **Scraping Engine:** `firecrawl` SDK
- **Validation:** `zod`
- **Config:** `dotenv`

---

## Requirements

- Node.js 18 or higher
- A [Firecrawl API key](https://www.firecrawl.dev) (free tier available)

---

## License

MIT