Servidor MCP

Use a API do Thunderbit através do Model Context Protocol — busque, faça scraping e extraia dados de qualquer host de AI compatível com MCP.

Um servidor Model Context Protocol (MCP) que integra o Thunderbit para destilar páginas em Markdown, extrair campos estruturados de qualquer página com instruções em linguagem natural e executar tarefas em lote com até 100 URLs por vez. Open source no GitHub e distribuído no npm como @thunderbit/mcp-server.

Recursos

Destile qualquer URL em Markdown limpo, pronto para LLM
Extraia dados estruturados com um mapa plano de nome-de-campo → instrução
Sugira automaticamente campos extraíveis com suggest_fields
Execute tarefas em lote com até 100 URLs e status baseado em polling
Sobrescrita de API key por chamada para agentes multi-tenant
Suporte auto-hospedado via THUNDERBIT_API_BASE_URL

Instalação

Obtenha sua API key no Thunderbit Dashboard.

Executando com npx

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

Instalação manual

npm install -g @thunderbit/mcp-server

Executando no Cursor

Edite ~/.cursor/mcp.json:

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

Após salvar, atualize a lista de servidores MCP em Cursor Settings → Features → MCP Servers. O Composer Agent usará o Thunderbit quando você perguntar sobre dados da web.

Executando no Windsurf

Adicione isto a ~/.codeium/windsurf/mcp_config.json:

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

Executando no VS Code

Para configuração compartilhada no workspace, crie .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}"
      }
    }
  }
}

Para configuração global de usuário, cole o mesmo bloco servers em User Settings (JSON) sob a chave mcp.

Executando no Claude Desktop

Edite ~/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"
      }
    }
  }
}

Se você ver spawn npx ENOENT, o Node.js não está no PATH do sistema. Instale o Node.js LTS do site oficial e reinicie o Claude Desktop completamente. No Windows, você também pode executar where npx e usar o caminho absoluto (ex.: C:\Program Files\nodejs\npx.cmd) como valor de command.

Executando no Claude Code

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

Executando no Cline

No painel MCP Servers do Cline, clique em Add Server e use:

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

Configuração

Variáveis de ambiente

Obrigatório

THUNDERBIT_API_KEY — sua API key (tb_ seguido de 32 caracteres hex). Obrigatório a menos que cada chamada de tool passe seu próprio argumento apiKey.

Opcional

THUNDERBIT_API_BASE_URL — apontar para um gateway auto-hospedado. Padrão: https://openapi.thunderbit.com
THUNDERBIT_TIMEOUT_MS — timeout HTTP por chamada. Padrão: 120000 (2 minutos). Aumente para polling de batch lento.

Exemplos de configuração

Para a API na nuvem com configurações padrão:

export THUNDERBIT_API_KEY=tb_your_key

Para instâncias auto-hospedadas:

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

Configuração personalizada com 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"
      }
    }
  }
}

Sobrescrita de API key por chamada

Cada tool aceita um argumento opcional apiKey que sobrescreve THUNDERBIT_API_KEY. Útil quando um servidor MCP atende múltiplos usuários finais:

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

Ferramentas disponíveis

1. Distill Tool (`thunderbit_distill`)

Converte qualquer página da web em Markdown limpo, pronto para LLM. Custa 1 crédito por chamada.

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

Opções da Distill Tool

url: URL da página da web a converter (obrigatório)
renderMode: none | basic | full — controla a profundidade de renderização JS
waitFor: Tempo de espera em ms após o carregamento da página (0–10000) — aumente para SPAs
includeTags: Tags HTML a incluir (ex.: ["article", "main"])
excludeTags: Tags HTML a excluir (ex.: ["nav", "footer"])
countryCode: Código ISO de 2 letras do país, em maiúsculas (padrão: US)
timeout: Timeout da requisição em ms (5000–60000)
apiKey: Sobrescreve a key da variável de ambiente para esta chamada

Ideal para: leitura de artigos, ingestão RAG, sumarização de páginas em massa, análise de conteúdo. Retorna: string Markdown.

2. Extract Tool (`thunderbit_extract`)

Extrai dados estruturados de uma página da web. O schema é um mapa plano de fieldName → instrução em linguagem natural. Custa 20 créditos por chamada.

Nota: a spec OpenAPI upstream descreve schema como JSON Schema. O servidor em produção espera o mapa plano de instruções mostrado abaixo; estamos alinhando a 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"
  }
}

O resultado data.data é sempre um array, mesmo quando você espera apenas um único registro:

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

Opções da Extract Tool

url: URL da página da web (obrigatório)
schema: Record<string, string> plano — nome do campo → instrução (obrigatório)
renderMode: none | basic | full
waitFor: Tempo de espera em ms após o carregamento da página (0–10000)
timeout: Timeout da requisição em ms (5000–120000)
apiKey: Sobrescrita de key por chamada

Ideal para: geração de leads, monitoramento de preços, análise competitiva, construção de datasets. Retorna: array data.data de objetos cujas chaves são os nomes dos campos do seu schema.

3. Suggest Fields Tool (`thunderbit_suggest_fields`)

Analisa uma página e propõe campos extraíveis. Use isso primeiro quando não souber quais dados a página contém. Custa 1 crédito por chamada.

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

Opções da Suggest Fields Tool

url: URL da página da web a analisar (obrigatório)
prompt: Dica opcional para orientar a AI
countryCode: Código ISO de 2 letras do país (padrão: US)
apiKey: Sobrescrita de key por chamada

Ideal para: descobrir o schema antes de executar o extract; iniciar novos alvos de scraping. Retorna: array de objetos { name, type, instruction }, prontos para alimentar thunderbit_extract.

4. Batch Distill Create (`thunderbit_batch_distill_create`)

Envie até 100 URLs para destilação. Retorna um job ID — faça polling em thunderbit_batch_distill_status até concluir. Custa 1 crédito por 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
  }
}

Opções de Batch Distill Create

urls: Array de URLs (1–100, obrigatório)
timeout: Timeout da requisição por página em ms (5000–60000)
apiKey: Sobrescrita de key por chamada

Ideal para: ingestão RAG em massa, destilação de site inteiro quando combinada com o endpoint Map. Retorna: { id, status, total } — passe id para a tool de status.

5. Batch Distill Status (`thunderbit_batch_distill_status`)

Faça polling em um job de batch distill e recupere resultados paginados. Gratuito.

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

Opções de Batch Distill Status

jobId: Job ID de thunderbit_batch_distill_create (obrigatório)
page: Índice de página baseado em 0 (padrão 0)
pageSize: Resultados por página, 1–100 (padrão 20)
apiKey: Sobrescrita de key por chamada

Ideal para: polling; recuperação do resultado final. Incremente page até results ficar vazio. Retorna: { id, status, total, completed, failed, creditsUsed, createdAt, completedAt, results: [{ index, url, success, markdown, error }, …] }. O status no nível do job é o enum (PENDING / PROCESSING / COMPLETED / FAILED / CANCELLED); cada item de resultado por URL usa um campo booleano success, e não status.

6. Batch Extract Create (`thunderbit_batch_extract_create`)

Envie até 100 URLs para extração com um único schema compartilhado. Custa 20 créditos por 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
  }
}

Opções de Batch Extract Create

urls: Array de URLs (1–100, obrigatório)
schema: Record<string, string> plano (campo → instrução) aplicado a cada URL (obrigatório)
timeout: Timeout da requisição por página em ms (5000–120000)
apiKey: Sobrescrita de key por chamada

Ideal para: scraping de catálogos, construção de datasets em larga escala. Retorna: { id, status, total }.

7. Batch Extract Status (`thunderbit_batch_extract_status`)

Faça polling em um job de batch extract. Gratuito.

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

Mesma estrutura de opções que thunderbit_batch_distill_status. Retorna dados extraídos paginados por URL.

Fluxo recomendado

thunderbit_suggest_fields — veja quais dados a página expõe
thunderbit_extract (ou thunderbit_distill) — extraia uma única URL
thunderbit_batch_*_create — distribua para até 100 URLs
thunderbit_batch_*_status — faça polling até o estado terminal

Tratamento de erros

Cada tool retorna erros como erros de tool MCP (isError: true) com uma dica estruturada, para que o modelo possa decidir se faz retry ou expõe a falha ao usuário.

// 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	Código	Dica emitida pelo servidor
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`	(sem dica, mensagem do servidor é repassada)

Lista completa de códigos: API Reference → Errors.

Solução de problemas

Tools não aparecem no host. Reinicie o host completamente após editar a configuração. O servidor registra uma linha de inicialização no stderr — verifique o arquivo de log MCP do host.

Cannot find module '@thunderbit/mcp-server'. Instale previamente (npm install -g @thunderbit/mcp-server) ou permita acesso de rede do npx no sandbox do host.

401 na primeira execução. O bloco env é por servidor — verifique se a key não está presa na entrada errada do servidor. Tente o caminho de instalação manual com a key exportada na shell para isolar.

Jobs em batch travam. A tool MCP apenas envia e faz polling; ela não mantém uma conexão de longa duração. Aumente THUNDERBIT_TIMEOUT_MS para 180000+ em batches grandes, ou combine batch_*_create com um webhook na sua aplicação para fire-and-forget.

CLI — mesmas operações, a partir da shell
Quickstart — HTTP puro, se preferir não usar MCP
API Reference — detalhes dos endpoints