Serveur MCP

Utilisez l'API de Thunderbit via le Model Context Protocol — recherchez, scrapez et extrayez depuis n'importe quel hôte IA compatible MCP.

Un serveur Model Context Protocol (MCP) qui intègre Thunderbit pour distiller des pages en Markdown, extraire des champs structurés depuis n'importe quelle page à l'aide d'instructions en langage naturel et exécuter des tâches en lot jusqu'à 100 URL à la fois. Open source sur GitHub et distribué sur npm sous le nom @thunderbit/mcp-server.

Fonctionnalités

Distillez n'importe quelle URL en Markdown propre, prêt pour les LLM
Extrayez des données structurées avec une map plate nom-de-champ → instruction
Suggérez automatiquement les champs extractibles avec suggest_fields
Exécutez des tâches en lot sur jusqu'à 100 URL avec un statut basé sur le polling
Surcharge de clé API par appel pour les agents multi-tenants
Prise en charge auto-hébergée via THUNDERBIT_API_BASE_URL

Installation

Récupérez votre clé API depuis le Thunderbit Dashboard.

Exécution avec npx

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

Installation manuelle

npm install -g @thunderbit/mcp-server

Exécution sur Cursor

Modifiez ~/.cursor/mcp.json :

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

Après avoir enregistré, actualisez la liste des serveurs MCP dans Cursor Settings → Features → MCP Servers. Le Composer Agent utilisera Thunderbit lorsque vous lui demanderez des données web.

Exécution sur Windsurf

Ajoutez ceci à ~/.codeium/windsurf/mcp_config.json :

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

Exécution sur VS Code

Pour une configuration partagée par espace de travail, créez .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}"
      }
    }
  }
}

Pour une configuration globale utilisateur, collez le même bloc servers dans User Settings (JSON) sous une clé mcp.

Exécution sur Claude Desktop

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

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

Si vous voyez spawn npx ENOENT, c'est que Node.js n'est pas dans le PATH système. Installez Node.js LTS depuis le site officiel et redémarrez Claude Desktop complètement. Sous Windows, vous pouvez également exécuter where npx et utiliser le chemin absolu (par exemple C:\Program Files\nodejs\npx.cmd) comme valeur de command.

Exécution sur Claude Code

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

Exécution sur Cline

Dans le panneau MCP Servers de Cline, cliquez sur Add Server et utilisez :

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

Configuration

Variables d'environnement

Requis

THUNDERBIT_API_KEY — votre clé API (tb_ suivi de 32 caractères hexadécimaux). Requis sauf si chaque appel d'outil transmet son propre argument apiKey.

Optionnel

THUNDERBIT_API_BASE_URL — pointer vers une passerelle auto-hébergée. Par défaut : https://openapi.thunderbit.com
THUNDERBIT_TIMEOUT_MS — timeout HTTP par appel. Par défaut : 120000 (2 minutes). Augmentez-le pour le polling lent des lots.

Exemples de configuration

Pour l'API cloud avec les paramètres par défaut :

export THUNDERBIT_API_KEY=tb_your_key

Pour les instances auto-hébergées :

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

Configuration personnalisée avec 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"
      }
    }
  }
}

Surcharge de clé API par appel

Chaque outil accepte un argument optionnel apiKey qui remplace THUNDERBIT_API_KEY. Utile lorsqu'un seul serveur MCP fait face à plusieurs utilisateurs finaux :

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

Outils disponibles

1. Distill Tool (`thunderbit_distill`)

Convertit n'importe quelle page web en Markdown propre, prêt pour les LLM. Coûte 1 crédit par appel.

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

Options du Distill Tool

url : URL de la page web à convertir (requis)
renderMode : none | basic | full — contrôle la profondeur du rendu JS
waitFor : temps d'attente en ms après le chargement de la page (0–10000) — augmentez pour les SPA
includeTags : balises HTML à inclure (par exemple ["article", "main"])
excludeTags : balises HTML à exclure (par exemple ["nav", "footer"])
countryCode : code pays ISO à 2 lettres, en majuscules (par défaut : US)
timeout : timeout de requête en ms (5000–60000)
apiKey : remplace la clé de la variable d'environnement pour cet appel

Idéal pour : lecture d'articles, ingestion RAG, résumé de pages en masse, analyse de contenu. Retourne : une chaîne Markdown.

2. Extract Tool (`thunderbit_extract`)

Extrait des données structurées d'une page web. Le schema est une map plate de fieldName → instruction en langage naturel. Coûte 20 crédits par appel.

Note : la spec OpenAPI en amont décrit schema comme un JSON Schema. Le serveur en production attend la map plate d'instructions présentée ci-dessous ; nous alignons 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"
  }
}

Le résultat data.data est toujours un tableau, même lorsque vous n'attendez qu'un seul enregistrement :

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

Options du Extract Tool

url : URL de la page web (requis)
schema : Record<string, string> plat — nom de champ → instruction (requis)
renderMode : none | basic | full
waitFor : temps d'attente en ms après le chargement de la page (0–10000)
timeout : timeout de requête en ms (5000–120000)
apiKey : surcharge de clé par appel

Idéal pour : génération de leads, surveillance de prix, analyse concurrentielle, constitution de jeux de données. Retourne : un tableau data.data d'objets dont les clés sont les noms de champ de votre schéma.

3. Suggest Fields Tool (`thunderbit_suggest_fields`)

Analyse une page et propose des champs extractibles. Utilisez-le en premier lorsque vous ne savez pas quelles données contient une page. Coûte 1 crédit par appel.

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

Options du Suggest Fields Tool

url : URL de la page web à analyser (requis)
prompt : indication facultative pour orienter l'AI
countryCode : code pays ISO à 2 lettres (par défaut : US)
apiKey : surcharge de clé par appel

Idéal pour : découvrir un schéma avant de lancer un extract ; amorcer de nouvelles cibles de scraping. Retourne : un tableau d'objets { name, type, instruction }, prêts à être passés à thunderbit_extract.

4. Batch Distill Create (`thunderbit_batch_distill_create`)

Soumettez jusqu'à 100 URL pour distillation. Renvoie un identifiant de tâche — interrogez thunderbit_batch_distill_status jusqu'à la fin. Coûte 1 crédit par 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
  }
}

Options du Batch Distill Create

urls : tableau d'URL (1–100, requis)
timeout : timeout de requête par page en ms (5000–60000)
apiKey : surcharge de clé par appel

Idéal pour : ingestion RAG en masse, distillation complète d'un site combinée à l'endpoint Map. Retourne : { id, status, total } — passez id à l'outil de statut.

5. Batch Distill Status (`thunderbit_batch_distill_status`)

Interrogez une tâche batch distill et récupérez les résultats paginés. Gratuit.

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

Options du Batch Distill Status

jobId : identifiant de tâche issu de thunderbit_batch_distill_create (requis)
page : index de page basé sur 0 (par défaut 0)
pageSize : résultats par page, 1–100 (par défaut 20)
apiKey : surcharge de clé par appel

Idéal pour : polling ; récupération du résultat final. Incrémentez page jusqu'à ce que results soit vide. Retourne : { id, status, total, completed, failed, creditsUsed, createdAt, completedAt, results: [{ index, url, success, markdown, error }, …] }. Le status au niveau du job est l'enum (PENDING / PROCESSING / COMPLETED / FAILED / CANCELLED) ; chaque item de résultat par URL utilise un champ booléen success, et non status.

6. Batch Extract Create (`thunderbit_batch_extract_create`)

Soumettez jusqu'à 100 URL pour extraction avec un schéma unique partagé. Coûte 20 crédits par 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
  }
}

Options du Batch Extract Create

urls : tableau d'URL (1–100, requis)
schema : Record<string, string> plat (champ → instruction) appliqué à chaque URL (requis)
timeout : timeout de requête par page en ms (5000–120000)
apiKey : surcharge de clé par appel

Idéal pour : scraping de catalogues, constitution de jeux de données à grande échelle. Retourne : { id, status, total }.

7. Batch Extract Status (`thunderbit_batch_extract_status`)

Interrogez une tâche batch extract. Gratuit.

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

Même structure d'options que thunderbit_batch_distill_status. Renvoie les données extraites paginées par URL.

Flux recommandé

thunderbit_suggest_fields — voyez quelles données la page expose
thunderbit_extract (ou thunderbit_distill) — récupérez une seule URL
thunderbit_batch_*_create — étendez à jusqu'à 100 URL
thunderbit_batch_*_status — interrogez jusqu'à l'état terminal

Gestion des erreurs

Chaque outil retourne les erreurs sous forme d'erreurs d'outil MCP (isError: true) avec une indication structurée, afin que le modèle puisse décider de réessayer ou de remonter l'échec à l'utilisateur.

// 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	Code	Indication émise par le serveur
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`	(aucune indication, le message du serveur est transmis tel quel)

Liste complète des codes : API Reference → Errors.

Dépannage

Les outils n'apparaissent pas dans l'hôte. Redémarrez l'hôte complètement après avoir modifié la configuration. Le serveur écrit une ligne de démarrage sur stderr — consultez le fichier journal MCP de l'hôte.

Cannot find module '@thunderbit/mcp-server'. Soit pré-installez (npm install -g @thunderbit/mcp-server), soit autorisez l'accès réseau de npx depuis la sandbox de l'hôte.

401 au premier lancement. Le bloc env est par serveur — vérifiez que la clé n'est pas piégée dans la mauvaise entrée serveur. Essayez le chemin d'installation manuel avec la clé exportée dans le shell pour isoler le problème.

Les tâches batch s'enlisent. L'outil MCP ne fait que soumettre et interroger ; il ne maintient pas de connexion longue durée. Augmentez THUNDERBIT_TIMEOUT_MS à 180000+ pour les gros lots, ou combinez batch_*_create avec un webhook dans votre application pour faire du fire-and-forget.

CLI — mêmes opérations, depuis le shell
Quickstart — HTTP brut si vous préférez ne pas utiliser MCP
API Reference — détails des endpoints