Sul livello gratuito senza chiave, `scrape`, `search` e `interact` funzionano senza una chiave API (limitati). Altri strumenti come `crawl`, `map`, `agent` e `extract` necessitano ancora di una chiave. Preferisci una chiave API o OAuth quando l'utente può registrarsi. Sblocca l'intero set di strumenti e limiti più alti. Con una chiave, usa:```
https://mcp.firecrawl.dev/{FIRECRAWL_API_KEY}/v2/mcp

### Installazione Manuale```bash
npm install -g firecrawl-mcp

### Esecuzione con Streamable HTTP in Modalità Locale

Per eseguire il server utilizzando Streamable HTTP in locale invece del trasporto stdio predefinito:```bash
env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp

### Esecuzione su VS Code

Per un'installazione con un clic, fai clic su uno dei pulsanti di installazione qui sotto...

[![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)

Per l'installazione manuale, aggiungi il seguente blocco JSON al file User Settings (JSON) in VS Code. Puoi farlo premendo `Ctrl + Shift + P` e digitando `Preferences: Open User Settings (JSON)`.```json
{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "Firecrawl API Key",
        "password": true
      }
    ],
    "servers": {
      "firecrawl": {
        "command": "npx",
        "args": ["-y", "firecrawl-mcp"],
        "env": {
          "FIRECRAWL_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

## Configurazione

### Variabili d'ambiente

#### Richieste per l'API Cloud

- `FIRECRAWL_API_KEY`: La tua chiave API Firecrawl
  - Richiesta quando si utilizza l'API cloud (predefinita)
  - Opzionale quando si utilizza un'istanza self-hosted con `FIRECRAWL_API_URL`
- `FIRECRAWL_API_URL` (Opzionale): Endpoint API personalizzato per istanze self-hosted
  - Esempio: `https://firecrawl.your-domain.com`
  - Se non fornito, verrà utilizzata l'API cloud (richiede la chiave API)

#### MCP OAuth (token di accesso Bearer)

Firecrawl hosted può emettere **token di accesso** OAuth (`fco_…`) tramite il server di autorizzazione su [firecrawl.dev](https://firecrawl.dev). Questo server MCP inoltra qualsiasi credenziale risolta all'API Firecrawl come `Authorization: Bearer …`.

- **Trasporti di stream HTTP** (`CLOUD_SERVICE=true`, `HTTP_STREAMABLE_SERVER=true` o `SSE_LOCAL=true`): I client dovrebbero inviare `Authorization: Bearer <fco_access_token>` nelle richieste MCP. Un token di accesso OAuth ha la precedenza su `x-firecrawl-api-key` / `x-api-key` quando entrambi sono presenti.
- **stdio:** Usa `FIRECRAWL_OAUTH_TOKEN` per un token di accesso statico, oppure continua a usare `FIRECRAWL_API_KEY` per una chiave API.

Usa solo token di **accesso** (`fco_…`). I token di aggiornamento (`fcr_…`) devono essere scambiati presso l'endpoint del token, non passati all'API di scraping/ricerca.

### Esempi di configurazione

Per l'utilizzo dell'API cloud:```bash
export FIRECRAWL_API_KEY=your-api-key

### Utilizzo con Claude Desktop

Aggiungi questo al tuo `claude_desktop_config.json`:```json
{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

**Esempio di utilizzo (formato markdown - quando è necessario il contenuto completo):**```json
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/article",
    "formats": ["markdown"],
    "onlyMainContent": true
  }
}

**Formato del branding:** Estrae un'identità di marca completa (colori, font, tipografia, spaziatura, logo, componenti UI) per analisi di design o replica di stili.
**Privacy:** Imposta `redactPII: true` per restituire contenuti con informazioni personali identificabili oscurate.

**Restituisce:**

- Dati strutturati JSON, markdown, profilo del branding o altri formati come specificato.

### 2. Strumento Map (`firecrawl_map`)

Mappa un sito web per scoprire tutti gli URL indicizzati sul sito.

**Ideale per:**

- Scoprire gli URL su un sito web prima di decidere cosa raschiare
- Trovare sezioni specifiche di un sito web

**Non raccomandato per:**

- Quando già sai quale URL specifico ti serve (usa scrape)
- Quando hai bisogno del contenuto delle pagine (usa scrape dopo la mappatura)

**Errori comuni:**

- Usare crawl per scoprire URL invece di map

**Esempio di prompt:**

> "Elenca tutti gli URL su example.com."

**Esempio di utilizzo:**```json
{
  "name": "firecrawl_map",
  "arguments": {
    "url": "https://example.com"
  }
}

**Restituisce:**

- Array di risultati di ricerca (con contenuto opzionale estratto), più un campo `id`. Passa quell'`id` a `firecrawl_search_feedback` dopo aver utilizzato i risultati per rimborsare 1 credito (la ricerca costa 2) e migliorare la qualità della ricerca.

**Esempio di prompt:**

> "Trova gli ultimi articoli di ricerca sull'IA pubblicati nel 2023."

### 3b. Strumento di Feedback per la Ricerca (`firecrawl_search_feedback`)

Invia un feedback strutturato su un risultato precedente di `firecrawl_search`. Il primo feedback per id di ricerca rimborsa 1 credito e migliora la qualità della ricerca di Firecrawl. Idempotente per id di ricerca.

**Chiamalo dopo ogni ricerca che usi effettivamente** (o che non è stata d'aiuto). Un feedback negativo o parziale con `missingContent` è altrettanto prezioso di un buon feedback.

**Rinuncia:** imposta `FIRECRAWL_NO_SEARCH_FEEDBACK=1` (o `FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1`) nell'ambiente all'avvio del server MCP. Lo strumento `firecrawl_search_feedback` non verrà registrato, quindi gli agenti non potranno chiamarlo. Gli amministratori del team possono anche disabilitare il feedback lato server; in tal caso lo strumento è registrato ma restituisce sempre `feedbackErrorCode: "TEAM_OPTED_OUT"`.

**Campo più importante:** `missingContent`. È un array di specifici pezzi di contenuto che l'agente si aspettava di trovare ma non ha trovato. Un inserimento per argomento mancante — questi si aggregano tra i team e ci dicono cosa indicizzare successivamente.

**Limite giornaliero di rimborso (per team, per giorno UTC, default 100 crediti).** Una volta che `creditsRefundedToday` di un team raggiunge `dailyRefundCap`, le successive richieste registrano ancora il feedback ma non rimborsano più crediti. La risposta imposta `dailyCapReached: true`. Gli agenti dovrebbero smettere di chiamare questo strumento per il resto del giorno UTC quando vedono quel flag.

**Esempio di utilizzo:**```json
{
  "name": "firecrawl_search_feedback",
  "arguments": {
    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "good",
    "valuableSources": [
      {
        "url": "https://docs.firecrawl.dev/features/search",
        "reason": "Most up-to-date description of /search."
      }
    ],
    "missingContent": [
      {
        "topic": "Pricing for the search endpoint",
        "description": "No pricing tier table for /search specifically."
      },
      { "topic": "Per-team rate limits" }
    ],
    "querySuggestions": "Boost docs.firecrawl.dev for queries that mention 'firecrawl'"
  }
}

**Returns:**

- `{ success, feedbackId, creditsRefunded, creditsRefundedToday?, dailyRefundCap?, dailyCapReached?, alreadySubmitted?, warning? }` JSON.

### 4. Strumento di Crawl (`firecrawl_crawl`)

Avvia un job di crawl, lo interroga fino a raggiungere uno stato terminale e restituisce lo stato/dati finali del crawl.

**Ideale per:**

- Estrarre contenuti da più pagine correlate, quando serve una copertura completa.

**Non consigliato per:**

- Estrarre contenuti da una singola pagina (usa scrape)
- Quando i limiti di token sono un problema (usa map + scrape per un controllo più stretto)
- Quando servono risultati rapidi (il crawl può essere lento)

**Attenzione:** Le risposte del crawl possono essere molto grandi e potrebbero superare i limiti di token. Limita la profondità del crawl e il numero di pagine, oppure usa map + scrape per un controllo più stretto.

**Errori comuni:**

- Impostare limit o maxDiscoveryDepth troppo alti (causa overflow di token)
- Usare il crawl per una singola pagina (usa invece scrape)

**Esempio di Prompt:**

> "Ottieni tutti i post del blog dai primi due livelli di example.com/blog."

**Esempio di Utilizzo:**```json
{
  "name": "firecrawl_crawl",
  "arguments": {
    "url": "https://example.com/blog/*",
    "maxDiscoveryDepth": 2,
    "limit": 100,
    "allowExternalLinks": false,
    "deduplicateSimilarURLs": true
  }
}

**Restituisce:**

- La risposta include lo stato del lavoro di crawling:

### 6. Parse Tool (`firecrawl_parse`)

Analizza file locali o riferimenti di upload ospitati con l'endpoint `/v2/parse` di Firecrawl.

**Ideale per:** PDF, documenti Word, fogli di calcolo, file HTML e altri documenti che necessitano di output markdown o JSON strutturato. L'MCP ospitato supporta un flusso in due passaggi (upload-ref); la lettura diretta di file locali richiede un `FIRECRAWL_API_URL` self-hosted.

**Sconsigliato per:** URL remoti (usa scrape), più file in una singola chiamata (chiama parse una volta per file) o azioni solo browser come screenshot e click.

**Flusso MCP ospitato:** L'MCP ospitato non può leggere direttamente il filesystem del chiamante. Chiama `firecrawl_parse` con `filePath` per ricevere un comando di upload a breve durata e `nextToolCall`, carica il file localmente, quindi chiama di nuovo `firecrawl_parse` con l'`uploadRef` restituito. Il conio dell'URL di upload ospitato richiede l'autenticazione Firecrawl o l'idoneità senza chiave. In modalità locale `npx firecrawl-mcp`, l'analisi diretta dei file richiede attualmente un `FIRECRAWL_API_URL` che punti a un'API Firecrawl self-hosted; un server locale semplice con solo chiave API cloud non può leggere e caricare file tramite questo strumento.

**Esempio di utilizzo:**```json
{
  "name": "firecrawl_parse",
  "arguments": {
    "filePath": "/absolute/path/to/document.pdf",
    "formats": ["markdown"],
    "parsers": ["pdf"],
    "zeroDataRetention": true
  }
}

**Restituisce:**

- Dati strutturati estratti come definito dal tuo schema```json
{
  "content": [
    {
      "type": "text",
      "text": {
        "name": "Example Product",
        "price": 99.99,
        "description": "This is an example product description"
      }
    }
  ],
  "isError": false
}

Interroga con `firecrawl_agent_status` utilizzando l'ID del job restituito.

**Esempio di utilizzo (con URL - l'agente si concentra su pagine specifiche):**```json
{
  "name": "firecrawl_agent",
  "arguments": {
    "urls": ["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
    "prompt": "Compare the features and pricing information from these pages"
  }
}

**Possible statuses:**

- `processing`: L'agente sta ancora ricercando - controlla più tardi
- `completed`: Ricerca completata - la risposta include i dati estratti
- `failed`: Si è verificato un errore

### 10. Interact Tool (`firecrawl_interact`)

Interagisci con un nuovo URL o con una pagina già aperta da `firecrawl_scrape`.

**Ideale per:** Fare clic, digitare, navigare ed estrarre lo stato da pagine dinamiche senza ripristinare gli strumenti del browser deprecati.

**Opzioni di utilizzo:**

- Passa `url` per raschiare e aprire una pagina per l'interazione in una singola chiamata MCP.
- Passa `scrapeId` per continuare a interagire con una pagina già raschiata.
- Passa esattamente uno tra `url` o `scrapeId`, più uno tra `prompt` o `code`.

**Esempio di utilizzo:**```json
{
  "name": "firecrawl_interact",
  "arguments": {
    "url": "https://example.com",
    "prompt": "Click the pricing link and summarize the visible plans"
  }
}

### 12. Strumenti di Ricerca (`firecrawl_research_*`)

Cerca e ispeziona articoli e repository GitHub attraverso gli strumenti di ricerca MCP.

**Strumenti di ricerca disponibili:**

- `firecrawl_research_search_papers`: cerca articoli di ricerca.
- `firecrawl_research_inspect_paper`: ispeziona un articolo.
- `firecrawl_research_related_papers`: trova articoli correlati.
- `firecrawl_research_read_paper`: leggi il contenuto dell'articolo.
- `firecrawl_research_search_github`: cerca repository GitHub.

**Ideale per:** Revisione della letteratura, ricerca di articoli e flussi di lavoro di scoperta di repository dove l'agente necessita di una superficie di ricerca mirata invece di un web scraping generico.

### 13. Strumenti di Monitoraggio (`firecrawl_monitor_*`)

Crea e gestisci monitoraggi periodici di pagine. I monitoraggi eseguono scraping o crawling programmati, confrontano ogni risultato con l'ultimo snapshot conservato e possono notificare tramite webhook o email.

**Ideale per:**

- Monitorare una o poche pagine nel tempo
- Avvisare su modifiche significative utilizzando un obiettivo in linguaggio naturale
- Tracciare la cronologia dei controlli e le differenze a livello di pagina

**Pattern di creazione consigliato:**

Usa `page` o `pages` più `goal`. Il server MCP costruisce la richiesta di monitoraggio con una pianificazione di 30 minuti e l'API abilita automaticamente il giudizio di cambiamento significativo.

Il giudizio di cambiamento significativo viene eseguito automaticamente quando `goal` è impostato. I webhook di pagina espongono `isMeaningful` e `judgment` sugli eventi `monitor.page`.

Scrivi gli obiettivi come istruzioni di monitoraggio concise di 2-3 frasi. Indica cosa dovrebbe attivare un avviso, preserva qualsiasi ambito fornito dall'utente e includi esclusioni specifiche dell'intento solo quando sono ovvie dalla richiesta. Il rumore generico come spazi bianchi, modifiche di sola formattazione, ID di richiesta, parametri di tracciamento, metadati generici e chrome di pagina non correlati è già gestito dal giudice, quindi non ripeterlo in ogni obiettivo. Se l'utente è vago, mantieni l'obiettivo ampio; se richiede un monitoraggio ampio o "qualsiasi cambiamento", preservalo. Se l'utente dice che non gli interessa qualcosa, includilo esplicitamente.```json
{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "page": "https://example.com/pricing",
    "goal": "Alert when pricing, packaging, or launch messaging changes."
  }
}

**Richieste di creazione avanzate:**

Passa `body` quando hai bisogno di target di crawl, tracciamento delle modifiche JSON, conservazione personalizzata, o controllo esplicito di `judgeEnabled`.```json
{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "body": {
      "name": "Docs monitor",
      "schedule": { "text": "hourly", "timezone": "UTC" },
      "goal": "Alert when docs pages add, remove, or materially change API behavior.",
      "targets": [{ "type": "crawl", "url": "https://example.com/docs" }]
    }
  }
}

## Gestione degli errori

Il server fornisce una gestione robusta degli errori:

- Errori di limite di frequenza API segnalati al client MCP
- Messaggi di errore dettagliati
- Resilienza di rete

Esempio di risposta di errore:```json
{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded"
    }
  ],
  "isError": true
}

### Contribuire

1. Forka il repository
2. Crea il tuo branch di feature
3. Esegui i test: `npm test`
4. Invia una pull request

### Ringraziamenti ai contributori

Grazie a [@vrknetha](https://github.com/vrknetha), [@cawstudios](https://caw.tech) per l'implementazione iniziale!

Grazie a MCP.so e Klavis AI per l'hosting e a [@gstarwd](https://github.com/gstarwd), [@xiangkaiz](https://github.com/xiangkaiz) e [@zihaolin96](https://github.com/zihaolin96) per aver integrato il nostro server.

## Licenza

Licenza MIT - consulta il file LICENSE per i dettagli