MCP-Server

Nutze Thunderbits API über das Model Context Protocol — suchen, scrapen und extrahieren aus jedem MCP-kompatiblen KI-Host.

Ein Model Context Protocol (MCP) Server, der Thunderbit integriert, um Seiten in Markdown zu destillieren, strukturierte Felder per Natural-Language-Anweisungen aus jeder Seite zu ziehen und Batch-Jobs mit bis zu 100 URLs gleichzeitig auszuführen. Open Source auf GitHub und auf npm als @thunderbit/mcp-server verfügbar.

Funktionen

Wandle jede URL in sauberes, LLM-fertiges Markdown um
Extrahiere strukturierte Daten mit einer flachen Map aus Feldname → Anweisung
Schlage extrahierbare Felder automatisch mit suggest_fields vor
Führe Batch-Jobs mit bis zu 100 URLs aus, mit pollbasiertem Status
API-Key-Override pro Aufruf für mandantenfähige Agenten
Self-Hosted-Unterstützung über THUNDERBIT_API_BASE_URL

Installation

Hol dir deinen API-Key im Thunderbit Dashboard.

Mit npx ausführen

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

Manuelle Installation

npm install -g @thunderbit/mcp-server

In Cursor ausführen

Bearbeite ~/.cursor/mcp.json:

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

Aktualisiere nach dem Speichern die MCP-Server-Liste in Cursor Settings → Features → MCP Servers. Der Composer Agent verwendet Thunderbit, sobald du nach Webdaten fragst.

In Windsurf ausführen

Füge dies in ~/.codeium/windsurf/mcp_config.json ein:

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

In VS Code ausführen

Für eine workspace-weite Konfiguration erstelle .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}"
      }
    }
  }
}

Für eine benutzerweite Konfiguration füge denselben servers-Block in die User Settings (JSON) unter dem Schlüssel mcp ein.

In Claude Desktop ausführen

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

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

Wenn du spawn npx ENOENT siehst, ist Node.js nicht im System-PATH. Installiere Node.js LTS von der offiziellen Seite und starte Claude Desktop vollständig neu. Unter Windows kannst du auch where npx ausführen und den absoluten Pfad (z. B. C:\Program Files\nodejs\npx.cmd) als command-Wert verwenden.

In Claude Code ausführen

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

In Cline ausführen

Klicke im MCP-Servers-Panel von Cline auf Add Server und nutze:

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

Konfiguration

Umgebungsvariablen

Erforderlich

THUNDERBIT_API_KEY — dein API-Key (tb_ gefolgt von 32 Hex-Zeichen). Erforderlich, sofern nicht jeder Tool-Aufruf seinen eigenen apiKey-Parameter mitgibt.

Optional

THUNDERBIT_API_BASE_URL — auf ein Self-Hosted-Gateway zeigen lassen. Standard: https://openapi.thunderbit.com
THUNDERBIT_TIMEOUT_MS — HTTP-Timeout pro Aufruf. Standard: 120000 (2 Minuten). Erhöhe diesen Wert für langsames Batch-Polling.

Konfigurationsbeispiele

Für die Cloud-API mit Standardeinstellungen:

export THUNDERBIT_API_KEY=tb_your_key

Für Self-Hosted-Instanzen:

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

Eigene Konfiguration mit 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"
      }
    }
  }
}

API-Key-Override pro Aufruf

Jedes Tool akzeptiert ein optionales apiKey-Argument, das THUNDERBIT_API_KEY überschreibt. Nützlich, wenn ein einzelner MCP-Server mehrere Endnutzer bedient:

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

Verfügbare Tools

1. Distill Tool (`thunderbit_distill`)

Wandelt jede Webseite in sauberes, LLM-fertiges Markdown um. Kostet 1 Credit pro Aufruf.

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

Distill-Tool-Optionen

url: URL der Webseite, die konvertiert werden soll (erforderlich)
renderMode: none | basic | full — steuert die JS-Rendering-Tiefe
waitFor: Wartezeit in ms nach dem Seitenladen (0–10000) — höher für SPAs
includeTags: HTML-Tags, die einbezogen werden sollen (z. B. ["article", "main"])
excludeTags: HTML-Tags, die ausgeschlossen werden sollen (z. B. ["nav", "footer"])
countryCode: ISO-2-Buchstaben-Ländercode, Großbuchstaben (Standard: US)
timeout: Request-Timeout in ms (5000–60000)
apiKey: Override für den Env-Var-Key bei diesem Aufruf

Am besten für: Artikel lesen, RAG-Ingestion, Massenseiten-Zusammenfassungen, Inhaltsanalyse. Rückgabe: Markdown-String.

2. Extract Tool (`thunderbit_extract`)

Extrahiert strukturierte Daten von einer Webseite. Das schema ist eine flache Map aus fieldName → Natural-Language-Anweisung. Kostet 20 Credits pro Aufruf.

Hinweis: Die vorgelagerte OpenAPI-Spec beschreibt schema als JSON Schema. Der Live-Server erwartet die unten gezeigte flache Anweisungs-Map; wir gleichen die Spec an.

{
  "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"
  }
}

Das Ergebnis data.data ist immer ein Array, auch wenn du nur einen einzelnen Datensatz erwartest:

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

Extract-Tool-Optionen

url: URL der Webseite (erforderlich)
schema: Flache Record<string, string> — Feldname → Anweisung (erforderlich)
renderMode: none | basic | full
waitFor: Wartezeit in ms nach dem Seitenladen (0–10000)
timeout: Request-Timeout in ms (5000–120000)
apiKey: Key-Override pro Aufruf

Am besten für: Lead-Generierung, Preisüberwachung, Wettbewerbsanalyse, Aufbau von Datensätzen. Rückgabe: data.data-Array von Objekten, deren Schlüssel die Feldnamen aus deinem Schema sind.

3. Suggest Fields Tool (`thunderbit_suggest_fields`)

Analysiert eine Seite und schlägt extrahierbare Felder vor. Verwende dies zuerst, wenn du nicht weißt, welche Daten eine Seite enthält. Kostet 1 Credit pro Aufruf.

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

Suggest-Fields-Tool-Optionen

url: URL der zu analysierenden Webseite (erforderlich)
prompt: Optionaler Steuerhinweis für die KI
countryCode: ISO-2-Buchstaben-Ländercode (Standard: US)
apiKey: Key-Override pro Aufruf

Am besten für: Schemafindung vor dem Extract-Lauf; Bootstrapping neuer Scrape-Ziele. Rückgabe: Array von { name, type, instruction }-Objekten, bereit für thunderbit_extract.

4. Batch Distill Create (`thunderbit_batch_distill_create`)

Sende bis zu 100 URLs zur Destillation. Gibt eine Job-ID zurück — polle thunderbit_batch_distill_status bis zum Abschluss. Kostet 1 Credit pro 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
  }
}

Batch-Distill-Create-Optionen

urls: Array von URLs (1–100, erforderlich)
timeout: Request-Timeout pro Seite in ms (5000–60000)
apiKey: Key-Override pro Aufruf

Am besten für: Massen-RAG-Ingestion, vollständige Site-Destillation in Kombination mit dem Map-Endpoint. Rückgabe: { id, status, total } — id an das Status-Tool übergeben.

5. Batch Distill Status (`thunderbit_batch_distill_status`)

Polle einen Batch-Distill-Job und ruf paginierte Ergebnisse ab. Kostenlos.

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

Batch-Distill-Status-Optionen

jobId: Job-ID aus thunderbit_batch_distill_create (erforderlich)
page: 0-basierter Seitenindex (Standard 0)
pageSize: Ergebnisse pro Seite, 1–100 (Standard 20)
apiKey: Key-Override pro Aufruf

Am besten für: Polling; finale Ergebnisabholung. Erhöhe page, bis results leer ist. Rückgabe: { id, status, total, completed, failed, creditsUsed, createdAt, completedAt, results: [{ index, url, success, markdown, error }, …] }. Der Job-Level-status ist das Enum (PENDING / PROCESSING / COMPLETED / FAILED / CANCELLED); jedes Per-URL-Ergebnis nutzt ein boolesches success-Feld, nicht status.

6. Batch Extract Create (`thunderbit_batch_extract_create`)

Sende bis zu 100 URLs zur Extraktion mit einem gemeinsamen Schema. Kostet 20 Credits pro 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
  }
}

Batch-Extract-Create-Optionen

urls: Array von URLs (1–100, erforderlich)
schema: Flache Record<string, string> (Feld → Anweisung), die auf jede URL angewendet wird (erforderlich)
timeout: Request-Timeout pro Seite in ms (5000–120000)
apiKey: Key-Override pro Aufruf

Am besten für: Katalog-Scraping, Aufbau großer Datensätze. Rückgabe: { id, status, total }.

7. Batch Extract Status (`thunderbit_batch_extract_status`)

Polle einen Batch-Extract-Job. Kostenlos.

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

Gleiche Optionsstruktur wie thunderbit_batch_distill_status. Liefert paginierte extrahierte Daten pro URL.

Empfohlener Workflow

thunderbit_suggest_fields — sieh, welche Daten die Seite preisgibt
thunderbit_extract (oder thunderbit_distill) — eine einzelne URL holen
thunderbit_batch_*_create — auf bis zu 100 URLs ausweiten
thunderbit_batch_*_status — pollen, bis terminal

Fehlerbehandlung

Jedes Tool gibt Fehler als MCP-Tool-Errors zurück (isError: true) mit einem strukturierten Hinweis, sodass das Modell entscheiden kann, ob es einen Retry versucht oder den Fehler an den Nutzer durchreicht.

// Pseudo-Code: Wie der Host einen Fehler empfängt
{
  isError: true,
  content: [{
    type: "text",
    text: "Thunderbit API error (402): INSUFFICIENT_CREDITS — Top up at https://thunderbit.com/billing"
  }]
}

HTTP	Code	Vom Server gelieferter Hinweis
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`	(kein Hinweis, Server-Meldung wird durchgereicht)

Vollständige Code-Liste: API Reference → Errors.

Troubleshooting

Tools erscheinen nicht im Host. Starte den Host nach Bearbeitung der Konfiguration vollständig neu. Der Server schreibt eine Startzeile auf stderr — prüfe die MCP-Logdatei des Hosts.

Cannot find module '@thunderbit/mcp-server'. Entweder vorab installieren (npm install -g @thunderbit/mcp-server) oder npx-Netzwerkzugriff aus der Sandbox des Hosts whitelisten.

401 beim ersten Lauf. Der env-Block gilt pro Server — prüfe, dass der Key nicht im falschen Server-Eintrag eingeschlossen ist. Probiere den manuellen Installationspfad mit dem Key in der Shell exportiert, um das Problem einzugrenzen.

Batch-Jobs hängen. Das MCP-Tool stellt nur den Job ein und pollt; es hält keine langlebige Verbindung. Erhöhe THUNDERBIT_TIMEOUT_MS für große Batches auf 180000+ oder kombiniere batch_*_create mit einem Webhook in deiner Anwendung für Fire-and-Forget.

CLI — dieselben Operationen, aus der Shell
Quickstart — rohes HTTP, falls du MCP nicht nutzen möchtest
API Reference — Endpoint-Details