MCP Server

Usa l'API di Thunderbit tramite il Model Context Protocol — cerca, esegui scraping ed estrai da qualsiasi host AI compatibile con MCP.

Un server Model Context Protocol (MCP) che integra Thunderbit per distillare pagine in Markdown, estrarre campi strutturati da qualsiasi pagina con istruzioni in linguaggio naturale ed eseguire job in batch fino a 100 URL alla volta. Open source su GitHub e distribuito su npm come @thunderbit/mcp-server.

Funzionalità

Trasforma qualsiasi URL in Markdown pulito e pronto per LLM
Estrai dati strutturati con una mappa piatta nome-campo → istruzione
Suggerisci automaticamente i campi estraibili con suggest_fields
Esegui job in batch fino a 100 URL con stato basato su polling
Override della chiave API per chiamata per agenti multi-tenant
Supporto self-hosted tramite THUNDERBIT_API_BASE_URL

Installazione

Ottieni la tua chiave API dalla Thunderbit Dashboard.

Esecuzione con npx

env THUNDERBIT_API_KEY=tb_YOUR_API_KEY npx -y @thunderbit/mcp-server

Installazione manuale

npm install -g @thunderbit/mcp-server

Esecuzione su Cursor

Modifica ~/.cursor/mcp.json:

{
  "mcpServers": {
    "thunderbit": {
      "command": "npx",
      "args": ["-y", "@thunderbit/mcp-server"],
      "env": {
        "THUNDERBIT_API_KEY": "tb_YOUR_API_KEY"
      }
    }
  }
}

Dopo aver salvato, aggiorna l'elenco dei server MCP in Cursor Settings → Features → MCP Servers. Il Composer Agent userà Thunderbit quando chiedi informazioni sui dati web.

Esecuzione su Windsurf

Aggiungi questo a ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "thunderbit": {
      "command": "npx",
      "args": ["-y", "@thunderbit/mcp-server"],
      "env": {
        "THUNDERBIT_API_KEY": "tb_YOUR_API_KEY"
      }
    }
  }
}

Esecuzione su VS Code

Per una configurazione condivisa a livello di workspace, crea .vscode/mcp.json:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "Thunderbit API Key",
      "password": true
    }
  ],
  "servers": {
    "thunderbit": {
      "command": "npx",
      "args": ["-y", "@thunderbit/mcp-server"],
      "env": {
        "THUNDERBIT_API_KEY": "${input:apiKey}"
      }
    }
  }
}

Per una configurazione globale a livello utente, incolla lo stesso blocco servers nelle User Settings (JSON) sotto una chiave mcp.

Esecuzione su Claude Desktop

Modifica ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "thunderbit": {
      "command": "npx",
      "args": ["-y", "@thunderbit/mcp-server"],
      "env": {
        "THUNDERBIT_API_KEY": "tb_YOUR_API_KEY"
      }
    }
  }
}

Se vedi spawn npx ENOENT, Node.js non è nel PATH di sistema. Installa Node.js LTS dal sito ufficiale e riavvia completamente Claude Desktop. Su Windows puoi anche eseguire where npx e usare il percorso assoluto (ad es. C:\Program Files\nodejs\npx.cmd) come valore di command.

Esecuzione su Claude Code

claude mcp add thunderbit -e THUNDERBIT_API_KEY=tb_YOUR_API_KEY -- npx -y @thunderbit/mcp-server

Esecuzione su Cline

Nel pannello MCP Servers di Cline, clicca Add Server e usa:

{
  "command": "npx",
  "args": ["-y", "@thunderbit/mcp-server"],
  "env": {
    "THUNDERBIT_API_KEY": "tb_YOUR_API_KEY"
  }
}

Configurazione

Variabili d'ambiente

Obbligatorie

THUNDERBIT_API_KEY — la tua chiave API (tb_ seguito da 32 caratteri esadecimali). Obbligatoria a meno che ogni chiamata di tool non passi il proprio argomento apiKey.

Opzionali

THUNDERBIT_API_BASE_URL — punta a un gateway self-hosted. Default: https://openapi.thunderbit.com
THUNDERBIT_TIMEOUT_MS — timeout HTTP per chiamata. Default: 120000 (2 minuti). Aumentalo per il polling lento dei batch.

Esempi di configurazione

Per l'API cloud con impostazioni predefinite:

export THUNDERBIT_API_KEY=tb_your_key

Per istanze self-hosted:

export THUNDERBIT_API_KEY=tb_your_key
export THUNDERBIT_API_BASE_URL=https://openapi.your-domain.com
export THUNDERBIT_TIMEOUT_MS=300000

Configurazione personalizzata con Claude Desktop

{
  "mcpServers": {
    "thunderbit": {
      "command": "npx",
      "args": ["-y", "@thunderbit/mcp-server"],
      "env": {
        "THUNDERBIT_API_KEY": "tb_YOUR_API_KEY",
        "THUNDERBIT_API_BASE_URL": "https://openapi.thunderbit.com",
        "THUNDERBIT_TIMEOUT_MS": "180000"
      }
    }
  }
}

Override della chiave API per chiamata

Ogni tool accetta un argomento opzionale apiKey che sovrascrive THUNDERBIT_API_KEY. Utile quando un singolo server MCP serve più utenti finali:

{
  "url": "https://example.com",
  "apiKey": "tb_customer_specific_key"
}

Strumenti disponibili

1. Distill Tool (`thunderbit_distill`)

Converte qualsiasi pagina web in Markdown pulito e pronto per LLM. Costa 1 credito per chiamata.

{
  "name": "thunderbit_distill",
  "arguments": {
    "url": "https://example.com/article",
    "renderMode": "basic",
    "waitFor": 1000,
    "includeTags": ["article", "main"],
    "excludeTags": ["nav", "footer"],
    "countryCode": "US",
    "timeout": 30000
  }
}

Opzioni di Distill Tool

url: URL della pagina web da convertire (obbligatorio)
renderMode: none | basic | full — controlla la profondità del rendering JS
waitFor: tempo di attesa in ms dopo il caricamento della pagina (0–10000) — aumentalo per le SPA
includeTags: tag HTML da includere (ad es. ["article", "main"])
excludeTags: tag HTML da escludere (ad es. ["nav", "footer"])
countryCode: codice paese ISO a 2 lettere, maiuscolo (default: US)
timeout: timeout della richiesta in ms (5000–60000)
apiKey: sovrascrive la chiave da variabile d'ambiente per questa chiamata

Ideale per: lettura di articoli, ingestione RAG, riassunto di pagine in massa, analisi dei contenuti. Restituisce: stringa Markdown.

2. Extract Tool (`thunderbit_extract`)

Estrae dati strutturati da una pagina web. Lo schema è una mappa piatta di fieldName → istruzione in linguaggio naturale. Costa 20 crediti per chiamata.

Nota: la spec OpenAPI a monte descrive schema come JSON Schema. Il server in produzione si aspetta la mappa piatta di istruzioni mostrata sotto; stiamo allineando la spec.

{
  "name": "thunderbit_extract",
  "arguments": {
    "url": "https://example.com/product",
    "schema": {
      "name": "product name",
      "price": "the listed price as a number",
      "currency": "3-letter currency code",
      "inStock": "true if the product is available, false otherwise"
    },
    "renderMode": "basic"
  }
}

Il risultato data.data è sempre un array, anche quando ti aspetti un singolo record:

{
  "data": {
    "url": "https://example.com/product",
    "data": [
      { "name": "iPhone 15 Pro", "price": 999, "currency": "USD", "inStock": true }
    ]
  }
}

Opzioni di Extract Tool

url: URL della pagina web (obbligatorio)
schema: Record<string, string> piatto — nome campo → istruzione (obbligatorio)
renderMode: none | basic | full
waitFor: tempo di attesa in ms dopo il caricamento della pagina (0–10000)
timeout: timeout della richiesta in ms (5000–120000)
apiKey: override della chiave per chiamata

Ideale per: lead generation, monitoraggio dei prezzi, analisi competitiva, costruzione di dataset. Restituisce: array data.data di oggetti le cui chiavi sono i nomi dei campi del tuo schema.

3. Suggest Fields Tool (`thunderbit_suggest_fields`)

Analizza una pagina e propone i campi estraibili. Usalo per primo quando non sai quali dati contiene una pagina. Costa 1 credito per chiamata.

{
  "name": "thunderbit_suggest_fields",
  "arguments": {
    "url": "https://example.com/product",
    "prompt": "Focus on pricing, availability, and shipping",
    "countryCode": "US"
  }
}

Opzioni di Suggest Fields Tool

url: URL della pagina web da analizzare (obbligatorio)
prompt: suggerimento opzionale per guidare l'AI
countryCode: codice paese ISO a 2 lettere (default: US)
apiKey: override della chiave per chiamata

Ideale per: scoprire lo schema prima di lanciare l'extract; bootstrap di nuovi target di scraping. Restituisce: array di oggetti { name, type, instruction }, pronti da passare a thunderbit_extract.

4. Batch Distill Create (`thunderbit_batch_distill_create`)

Invia fino a 100 URL per la distillazione. Restituisce un job ID — fai polling su thunderbit_batch_distill_status fino al completamento. Costa 1 credito per URL.

{
  "name": "thunderbit_batch_distill_create",
  "arguments": {
    "urls": [
      "https://example.com/page-1",
      "https://example.com/page-2",
      "https://example.com/page-3"
    ],
    "timeout": 30000
  }
}

Opzioni di Batch Distill Create

urls: array di URL (1–100, obbligatorio)
timeout: timeout della richiesta per pagina in ms (5000–60000)
apiKey: override della chiave per chiamata

Ideale per: ingestione RAG in massa, distillazione completa di un sito in combinazione con l'endpoint Map. Restituisce: { id, status, total } — passa id allo strumento di stato.

5. Batch Distill Status (`thunderbit_batch_distill_status`)

Esegue il polling di un job di batch distill e recupera i risultati paginati. Gratuito.

{
  "name": "thunderbit_batch_distill_status",
  "arguments": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "page": 0,
    "pageSize": 20
  }
}

Opzioni di Batch Distill Status

jobId: job ID restituito da thunderbit_batch_distill_create (obbligatorio)
page: indice di pagina basato su 0 (default 0)
pageSize: risultati per pagina, 1–100 (default 20)
apiKey: override della chiave per chiamata

Ideale per: polling; recupero del risultato finale. Incrementa page finché results non è vuoto. Restituisce: { id, status, total, completed, failed, creditsUsed, createdAt, completedAt, results: [{ index, url, success, markdown, error }, …] }. Lo status a livello di job è l'enum (PENDING / PROCESSING / COMPLETED / FAILED / CANCELLED); ogni elemento di risultato per URL usa un campo booleano success, non status.

6. Batch Extract Create (`thunderbit_batch_extract_create`)

Invia fino a 100 URL per l'estrazione con un singolo schema condiviso. Costa 20 crediti per URL.

{
  "name": "thunderbit_batch_extract_create",
  "arguments": {
    "urls": [
      "https://example.com/product-1",
      "https://example.com/product-2"
    ],
    "schema": {
      "name": "product name",
      "price": "the listed price as a number"
    },
    "timeout": 60000
  }
}

Opzioni di Batch Extract Create

urls: array di URL (1–100, obbligatorio)
schema: Record<string, string> piatto (campo → istruzione) applicato a ogni URL (obbligatorio)
timeout: timeout della richiesta per pagina in ms (5000–120000)
apiKey: override della chiave per chiamata

Ideale per: scraping di cataloghi, costruzione di dataset su larga scala. Restituisce: { id, status, total }.

7. Batch Extract Status (`thunderbit_batch_extract_status`)

Esegue il polling di un job di batch extract. Gratuito.

{
  "name": "thunderbit_batch_extract_status",
  "arguments": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "page": 0,
    "pageSize": 20
  }
}

Stessa struttura di opzioni di thunderbit_batch_distill_status. Restituisce i dati estratti paginati per URL.

Flusso consigliato

thunderbit_suggest_fields — vedi quali dati espone la pagina
thunderbit_extract (o thunderbit_distill) — estrai un singolo URL
thunderbit_batch_*_create — espandi fino a 100 URL
thunderbit_batch_*_status — fai polling fino allo stato terminale

Gestione degli errori

Ogni tool restituisce gli errori come MCP tool error (isError: true) con un suggerimento strutturato, così il modello può decidere se ritentare o mostrare il fallimento all'utente.

// Pseudo-code: how the host receives an error
{
  isError: true,
  content: [{
    type: "text",
    text: "Thunderbit API error (402): INSUFFICIENT_CREDITS — Top up at https://thunderbit.com/billing"
  }]
}

HTTP	Codice	Suggerimento emesso dal server
401	`API_KEY_INVALID_FORMAT` / `API_KEY_NOT_FOUND`	"Check your API key at https://app.thunderbit.com/console"
402	`INSUFFICIENT_CREDITS`	"Top up at https://thunderbit.com/billing"
429	`RATE_LIMIT_EXCEEDED`	"Rate limit exceeded, retry later"
5xx	`INTERNAL_ERROR` / `DISTILL_FAILED`	(nessun suggerimento, viene inoltrato il messaggio del server)

Elenco completo dei codici: API Reference → Errors.

Risoluzione dei problemi

I tool non compaiono nell'host. Riavvia completamente l'host dopo aver modificato la configurazione. Il server scrive una riga di avvio su stderr — controlla il file di log MCP dell'host.

Cannot find module '@thunderbit/mcp-server'. Preinstalla (npm install -g @thunderbit/mcp-server) oppure abilita l'accesso di rete a npx dalla sandbox dell'host.

401 alla prima esecuzione. Il blocco env è per server — verifica che la chiave non sia finita nella voce sbagliata. Prova il percorso di installazione manuale con la chiave esportata nella shell per isolare il problema.

I job in batch si bloccano. Il tool MCP si limita a inviare e fare polling; non mantiene una connessione di lunga durata. Aumenta THUNDERBIT_TIMEOUT_MS a 180000+ per batch grandi, oppure abbina batch_*_create a un webhook nella tua applicazione per un approccio fire-and-forget.

CLI — stesse operazioni, dalla shell
Quickstart — HTTP grezzo se preferisci non usare MCP
API Reference — dettagli sugli endpoint