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 是 字段名 → 自然语言指令 的扁平 map（每个值是 AI 在页面上定位该字段的提示）。每次调用消耗 20 个 credit。

注意：上游 OpenAPI spec 把 schema 描述为 JSON Schema。线上服务实际接受下方的扁平指令 map，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"
  }
}

返回的 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。

特性

安装