MCP 伺服器

透過 Model Context Protocol 使用 Thunderbit API —— 在任何相容 MCP 的 AI 主機中搜尋、抓取與擷取資料。

一個 Model Context Protocol (MCP) 伺服器，整合 Thunderbit 能力：將網頁蒸餾成 Markdown、用自然語言指令從任意頁面擷取結構化欄位、單次最多 100 個 URL 的批次任務。開源儲存庫在 GitHub，npm 套件名稱為 @thunderbit/mcp-server。

特性

將任意 URL 蒸餾為乾淨、適合 LLM 的 Markdown
用「欄位名 → 指令」的扁平映射擷取結構化資料
使用 suggest_fields 自動推薦可擷取欄位
對最多 100 個 URL 執行批次任務，並以輪詢方式查狀態
單次呼叫 API key 覆寫，方便多租戶 Agent
透過 THUNDERBIT_API_BASE_URL 支援自架

安裝

請至 app.thunderbit.com/console 取得你的 API key。

透過 npx 執行

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

手動安裝

npm install -g @thunderbit/mcp-server

在 Cursor 中執行

編輯 ~/.cursor/mcp.json：

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

儲存後，請到 Cursor Settings → Features → MCP Servers 中重新整理 MCP 伺服器列表。當你向 Composer Agent 詢問網頁資料相關問題時，它就會呼叫 Thunderbit。

在 Windsurf 中執行

把以下內容加進 ~/.codeium/windsurf/mcp_config.json：

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

在 VS Code 中執行

工作區共享設定請建立 .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}"
      }
    }
  }
}

如需使用者全域設定，請把同一個 servers 區塊貼到 User Settings (JSON) 的 mcp 鍵下。

在 Claude Desktop 中執行

編輯 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)：

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

如果看到 spawn npx ENOENT，代表 Node.js 不在系統 PATH 中。請從 nodejs.org 安裝 Node.js LTS，然後完整重新啟動 Claude Desktop。在 Windows 上你也可以執行 where npx，把絕對路徑（例如 C:\Program Files\nodejs\npx.cmd）作為 command 的值。

在 Claude Code 中執行

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

在 Cline 中執行

在 Cline 的 MCP Servers 面板中，按 Add Server 並填入：

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

設定

環境變數

必需

THUNDERBIT_API_KEY —— 你的 API key（tb_ 後接 32 位十六進位字元）。除非每次工具呼叫都自帶 apiKey 參數，否則必填。

可選

THUNDERBIT_API_BASE_URL —— 指向自架閘道。預設值：https://openapi.thunderbit.com
THUNDERBIT_TIMEOUT_MS —— 單次呼叫 HTTP 逾時。預設值：120000（2 分鐘）。批次輪詢較慢時可調高。

設定範例

雲端 API 預設設定：

export THUNDERBIT_API_KEY=tb_your_key

自架實例：

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

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 覆寫

每個工具都可接受可選的 apiKey 參數，會覆寫 THUNDERBIT_API_KEY。當一台 MCP 伺服器服務多個終端使用者時特別好用：

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

可用工具

1. Distill 工具 (`thunderbit_distill`)

把任意網頁轉成乾淨、適合 LLM 的 Markdown。每次呼叫消耗 1 個 credit。

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

Distill 工具選項

url：要轉換的網頁 URL（必填）
renderMode：none | basic | full —— 控制 JS 渲染深度
waitFor：頁面載入後的等待時間（毫秒，0–10000）—— SPA 可調高
includeTags：要包含的 HTML 標籤（例如 ["article", "main"])
excludeTags：要排除的 HTML 標籤（例如 ["nav", "footer"])
countryCode：ISO 兩位國碼，大寫（預設值：US）
timeout：請求逾時（毫秒，5000–60000）
apiKey：覆寫該次呼叫的環境變數 key

適用場景： 文章閱讀、RAG 資料匯入、批次頁面摘要、內容分析。 返回： Markdown 字串。

2. Extract 工具 (`thunderbit_extract`)

從網頁擷取結構化資料。schema 是 fieldName → 自然語言指令 的扁平映射。每次呼叫消耗 20 個 credit。

註：上游 OpenAPI 規範把 schema 描述為 JSON Schema。線上伺服器期望下方所示的扁平指令映射，我們正在對齊規範。

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

結果中的 data.data 永遠是陣列，即便你只期望返回單筆紀錄：

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

Extract 工具選項

url：網頁 URL（必填）
schema：扁平的 Record<string, string> —— 欄位名 → 指令（必填）
renderMode：none | basic | full
waitFor：頁面載入後的等待時間（毫秒，0–10000）
timeout：請求逾時（毫秒，5000–120000）
apiKey：單次呼叫 key 覆寫

適用場景： 名單開發、價格監控、競品分析、資料集建置。 返回： data.data 陣列，元素物件以你 schema 中的欄位名為鍵。

3. Suggest Fields 工具 (`thunderbit_suggest_fields`)

分析頁面並推薦可擷取欄位。當你不知道頁面包含哪些資料時請先用它。每次呼叫消耗 1 個 credit。

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

Suggest Fields 工具選項

url：要分析的網頁 URL（必填）
prompt：可選的 AI 引導提示
countryCode：ISO 兩位國碼（預設值：US）
apiKey：單次呼叫 key 覆寫

適用場景： 在執行 extract 前先發現 schema；為新的抓取目標做冷啟動。 返回： { name, type, instruction } 物件陣列，可直接餵給 thunderbit_extract。

4. Batch Distill Create (`thunderbit_batch_distill_create`)

提交最多 100 個 URL 進行蒸餾。回傳 job ID —— 透過 thunderbit_batch_distill_status 輪詢直到完成。每個 URL 消耗 1 個 credit。

{
  "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 選項

urls：URL 陣列（1–100，必填）
timeout：每頁請求逾時（毫秒，5000–60000）
apiKey：單次呼叫 key 覆寫

適用場景： 批次 RAG 資料匯入；與 Map 端點搭配做整站蒸餾。 返回： { id, status, total } —— 把 id 傳給狀態工具。

5. Batch Distill Status (`thunderbit_batch_distill_status`)

輪詢批次蒸餾任務並分頁取得結果。免費。

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

Batch Distill Status 選項

jobId：來自 thunderbit_batch_distill_create 的 job ID（必填）
page：從 0 開始的頁索引（預設值 0）
pageSize：每頁結果數，1–100（預設值 20）
apiKey：單次呼叫 key 覆寫

適用場景： 輪詢；最終結果取回。遞增 page，直到 results 為空。 返回： { id, status, total, completed, failed, creditsUsed, createdAt, completedAt, results: [{ index, url, success, markdown, error }, …] }。任務級 status 是列舉（PENDING / PROCESSING / COMPLETED / FAILED / CANCELLED）；每個 URL 的結果項使用布林 success 欄位，而非 status。

6. Batch Extract Create (`thunderbit_batch_extract_create`)

用一份共享 schema 提交最多 100 個 URL 進行擷取。每個 URL 消耗 20 個 credit。

{
  "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 選項

urls：URL 陣列（1–100，必填）
schema：套用於每個 URL 的扁平 Record<string, string>（欄位 → 指令，必填）
timeout：每頁請求逾時（毫秒，5000–120000）
apiKey：單次呼叫 key 覆寫

適用場景： 商品目錄抓取、大規模資料集建置。 返回： { id, status, total }。

7. Batch Extract Status (`thunderbit_batch_extract_status`)

輪詢批次擷取任務。免費。

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

參數形式與 thunderbit_batch_distill_status 相同。回傳每個 URL 的分頁擷取資料。

錯誤處理

每個工具都會以 MCP 工具錯誤（isError: true）形式回傳錯誤，並附帶結構化提示，讓模型決定要重試或把錯誤拋給使用者。

// 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	伺服器輸出的提示
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`	（無提示，原樣透傳伺服器訊息）

完整錯誤碼列表：API Reference → Errors。

故障排查

工具沒有出現在主機裡。 改完設定後請完整重新啟動主機。伺服器會在 stderr 印一行啟動訊息 —— 檢查主機的 MCP 紀錄檔。

Cannot find module '@thunderbit/mcp-server'。 要嘛預先安裝（npm install -g @thunderbit/mcp-server），要嘛在主機沙箱中允許 npx 連網。

首次執行回 401。 env 區塊是按伺服器作用域 —— 確認 key 沒有被誤放到別的伺服器條目下。改用手動安裝路徑、把 key export 到 shell，便於隔離排查。

批次任務卡住。 MCP 工具只負責提交與輪詢，並不會維持長連線。大批次時把 THUNDERBIT_TIMEOUT_MS 調到 180000 以上，或在你的應用裡把 batch_*_create 與 webhook 搭配，做到送出即離開。

自訂伺服器

想要自訂工具集合（不同的提示、範圍、過濾、額外工具）？請參考 MCP 整合指南，了解如何用 @modelcontextprotocol/sdk 從零建構伺服器。

開源

@thunderbit/mcp-server 採用 MIT 授權開源，儲存庫在 GitHub：thunderbit-open/thunderbit-mcp-server。

特性

安裝