MCP Server

Gebruik de API van Thunderbit via het Model Context Protocol — zoek, scrape en extraheer vanuit elke MCP-compatibele AI-host.

Een Model Context Protocol (MCP) server die Thunderbit integreert om pagina's te distilleren tot Markdown, gestructureerde velden uit elke pagina te halen met natuurlijke-taalinstructies en batch-jobs uit te voeren met tot 100 URLs tegelijk. Open-source op GitHub en gedistribueerd op npm als @thunderbit/mcp-server.

Functies

Distilleer elke URL tot schone, LLM-klare Markdown
Extraheer gestructureerde data met een platte map van veldnaam → instructie
Stel automatisch extraheerbare velden voor met suggest_fields
Voer batch-jobs uit op tot 100 URLs met poll-gebaseerde status
Per-call API-key override voor multi-tenant agents
Self-hosted ondersteuning via THUNDERBIT_API_BASE_URL

Installatie

Haal je API key op in het Thunderbit Dashboard.

Draaien met npx

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

Handmatige installatie

npm install -g @thunderbit/mcp-server

Draaien op Cursor

Bewerk ~/.cursor/mcp.json:

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

Vernieuw na het opslaan de MCP-serverlijst in Cursor Settings → Features → MCP Servers. De Composer Agent gebruikt Thunderbit zodra je naar webdata vraagt.

Draaien op Windsurf

Voeg dit toe aan ~/.codeium/windsurf/mcp_config.json:

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

Draaien op VS Code

Voor een workspace-gedeelde configuratie maak je .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}"
      }
    }
  }
}

Voor een gebruiker-globale configuratie plak je hetzelfde servers-blok in User Settings (JSON) onder een mcp-sleutel.

Draaien op Claude Desktop

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

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

Als je spawn npx ENOENT ziet, staat Node.js niet in het systeem-PATH. Installeer Node.js LTS van de officiële site en herstart Claude Desktop volledig. Op Windows kun je ook where npx uitvoeren en het absolute pad (bijv. C:\Program Files\nodejs\npx.cmd) als command-waarde gebruiken.

Draaien op Claude Code

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

Draaien op Cline

Klik in het MCP Servers-paneel van Cline op Add Server en gebruik:

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

Configuratie

Omgevingsvariabelen

Vereist

THUNDERBIT_API_KEY — je API key (tb_ gevolgd door 32 hex-tekens). Vereist tenzij elke tool-call zijn eigen apiKey-argument meegeeft.

Optioneel

THUNDERBIT_API_BASE_URL — verwijs naar een self-hosted gateway. Standaard: https://openapi.thunderbit.com
THUNDERBIT_TIMEOUT_MS — HTTP-timeout per call. Standaard: 120000 (2 minuten). Verhoog deze waarde voor traag batch-pollen.

Configuratievoorbeelden

Voor de cloud-API met standaardinstellingen:

export THUNDERBIT_API_KEY=tb_your_key

Voor self-hosted instances:

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

Aangepaste configuratie met 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"
      }
    }
  }
}

Per-call API-key override

Elke tool accepteert een optioneel apiKey-argument dat THUNDERBIT_API_KEY overschrijft. Handig wanneer één MCP-server meerdere eindgebruikers bedient:

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

Beschikbare tools

1. Distill Tool (`thunderbit_distill`)

Zet elke webpagina om in schone, LLM-klare Markdown. Kost 1 credit per call.

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

url: URL van de webpagina die geconverteerd moet worden (vereist)
renderMode: none | basic | full — bepaalt de JS-renderdiepte
waitFor: Wachttijd in ms na het laden van de pagina (0–10000) — verhogen voor SPA's
includeTags: HTML-tags die opgenomen moeten worden (bijv. ["article", "main"])
excludeTags: HTML-tags die uitgesloten moeten worden (bijv. ["nav", "footer"])
countryCode: ISO-2-letter landcode, hoofdletters (standaard: US)
timeout: Request-timeout in ms (5000–60000)
apiKey: Override voor de env-var-key bij deze call

Geschikt voor: Artikelen lezen, RAG-ingestie, bulk paginasamenvatting, contentanalyse. Retourneert: Markdown-string.

2. Extract Tool (`thunderbit_extract`)

Extraheer gestructureerde data uit een webpagina. Het schema is een platte map van fieldName → natuurlijke-taalinstructie. Kost 20 credits per call.

Opmerking: de upstream OpenAPI-spec beschrijft schema als JSON Schema. De live server verwacht de hieronder getoonde platte instructie-map; we trekken de spec gelijk.

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

Het resultaat data.data is altijd een array, ook als je maar één record verwacht:

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

Extract Tool-opties

url: URL van de webpagina (vereist)
schema: Platte Record<string, string> — veldnaam → instructie (vereist)
renderMode: none | basic | full
waitFor: Wachttijd in ms na het laden van de pagina (0–10000)
timeout: Request-timeout in ms (5000–120000)
apiKey: Per-call key-override

Geschikt voor: Lead generation, prijsmonitoring, concurrentieanalyse, datasetopbouw. Retourneert: data.data-array van objecten met de veldnamen uit jouw schema als sleutels.

3. Suggest Fields Tool (`thunderbit_suggest_fields`)

Analyseer een pagina en stel extraheerbare velden voor. Gebruik dit eerst wanneer je niet weet welke data een pagina bevat. Kost 1 credit per call.

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

Suggest Fields Tool-opties

url: URL van de te analyseren webpagina (vereist)
prompt: Optionele sturingshint voor de AI
countryCode: ISO-2-letter landcode (standaard: US)
apiKey: Per-call key-override

Geschikt voor: Schemafindling vóór een extract-run; bootstrappen van nieuwe scrape-doelen. Retourneert: Array van { name, type, instruction }-objecten, klaar om door te geven aan thunderbit_extract.

4. Batch Distill Create (`thunderbit_batch_distill_create`)

Dien tot 100 URLs in voor distillatie. Geeft een job-ID terug — poll thunderbit_batch_distill_status tot het klaar is. Kost 1 credit 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
  }
}

Batch Distill Create-opties

urls: Array van URLs (1–100, vereist)
timeout: Request-timeout per pagina in ms (5000–60000)
apiKey: Per-call key-override

Geschikt voor: Bulk RAG-ingestie, volledige site-distillatie in combinatie met het Map-endpoint. Retourneert: { id, status, total } — geef id door aan de status-tool.

5. Batch Distill Status (`thunderbit_batch_distill_status`)

Poll een batch-distill-job en haal gepagineerde resultaten op. Gratis.

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

Batch Distill Status-opties

jobId: Job-ID uit thunderbit_batch_distill_create (vereist)
page: 0-gebaseerde pagina-index (standaard 0)
pageSize: Resultaten per pagina, 1–100 (standaard 20)
apiKey: Per-call key-override

Geschikt voor: Pollen; ophalen van eindresultaten. Verhoog page totdat results leeg is. Retourneert: { id, status, total, completed, failed, creditsUsed, createdAt, completedAt, results: [{ index, url, success, markdown, error }, …] }. De status op job-niveau is de enum (PENDING / PROCESSING / COMPLETED / FAILED / CANCELLED); elk resultaat per URL gebruikt een boolean success-veld, niet status.

6. Batch Extract Create (`thunderbit_batch_extract_create`)

Dien tot 100 URLs in voor extractie met één gedeeld schema. Kost 20 credits 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
  }
}

Batch Extract Create-opties

urls: Array van URLs (1–100, vereist)
schema: Platte Record<string, string> (veld → instructie) die op elke URL wordt toegepast (vereist)
timeout: Request-timeout per pagina in ms (5000–120000)
apiKey: Per-call key-override

Geschikt voor: Catalogus-scraping, opbouw van grootschalige datasets. Retourneert: { id, status, total }.

7. Batch Extract Status (`thunderbit_batch_extract_status`)

Poll een batch-extract-job. Gratis.

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

Zelfde optiestructuur als thunderbit_batch_distill_status. Geeft per URL gepagineerde geëxtraheerde data terug.

Aanbevolen werkstroom

thunderbit_suggest_fields — kijk welke data de pagina prijsgeeft
thunderbit_extract (of thunderbit_distill) — haal één URL op
thunderbit_batch_*_create — schaal uit naar tot 100 URLs
thunderbit_batch_*_status — poll tot terminaal

Foutafhandeling

Elke tool retourneert fouten als MCP-tool-fouten (isError: true) met een gestructureerde hint, zodat het model kan beslissen om opnieuw te proberen of de fout aan de gebruiker te tonen.

// 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	Hint geleverd door de 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`	(geen hint, server-bericht wordt doorgegeven)

Volledige codelijst: API Reference → Errors.

Probleemoplossing

Tools verschijnen niet in de host. Herstart de host volledig na het bewerken van de configuratie. De server schrijft een opstartregel naar stderr — controleer het MCP-logbestand van de host.

Cannot find module '@thunderbit/mcp-server'. Installeer vooraf (npm install -g @thunderbit/mcp-server) of zet npx-netwerktoegang vanuit de sandbox van de host op de whitelist.

401 bij de eerste run. Het env-blok geldt per server — controleer of de key niet vastzit in het verkeerde server-entry. Probeer het handmatige installatiepad met de key in de shell geëxporteerd om het probleem te isoleren.

Batch-jobs lopen vast. De MCP-tool dient alleen in en pollt; hij houdt geen langdurige verbinding open. Verhoog THUNDERBIT_TIMEOUT_MS naar 180000+ voor grote batches, of combineer batch_*_create met een webhook in je applicatie voor fire-and-forget.

CLI — dezelfde operaties, vanuit de shell
Quickstart — rauw HTTP als je liever geen MCP gebruikt
API Reference — endpoint-details