MCP サーバー

Model Context Protocol 経由で Thunderbit API を使う —— 任意の MCP 互換 AI ホストから検索・スクレイピング・抽出。

Thunderbit を統合する Model Context Protocol (MCP) サーバー。ページを Markdown に蒸留し、自然言語の指示で任意のページから構造化フィールドを抽出し、最大 100 URL のバッチジョブを 1 度に実行できます。GitHub でオープンソース、npm では @thunderbit/mcp-server として配布されています。

機能

任意の URL をクリーンで LLM 向けの Markdown に蒸留
フィールド名 → 指示のフラットマップで構造化データを抽出
suggest_fields で抽出可能なフィールドを自動提案
最大 100 URL のバッチジョブをポーリングで状態確認
マルチテナント Agent 向けの呼び出しごとの API key 上書き
THUNDERBIT_API_BASE_URL によるセルフホスト対応

インストール

API key は app.thunderbit.com/console から取得してください。

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 サーバー一覧を更新してください。Web データに関する質問をすると 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 桁の 16 進数）。すべてのツール呼び出しが個別に 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 を上書きします。1 つの MCP サーバーが複数のエンドユーザーをホストしているときに便利です：

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

利用可能なツール

1. Distill ツール (`thunderbit_distill`)

任意の Web ページをクリーンで LLM 向けの Markdown に変換します。1 回の呼び出しで 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：変換対象の Web ページ URL（必須）
renderMode：none | basic | full — JS レンダリング深度を制御
waitFor：ページ読み込み後の待機時間（ミリ秒、0–10000）— SPA では引き上げる
includeTags：含める HTML タグ（例：["article", "main"])
excludeTags：除外する HTML タグ（例：["nav", "footer"])
countryCode：ISO 2 文字国コード（大文字、デフォルト：US）
timeout：リクエストタイムアウト（ミリ秒、5000–60000）
apiKey：この呼び出しに対して環境変数の key を上書き

ベスト用途： 記事閲覧、RAG 取り込み、大量ページ要約、コンテンツ分析。 戻り値： Markdown 文字列。

2. Extract ツール (`thunderbit_extract`)

Web ページから構造化データを抽出します。schema は fieldName → 自然言語の指示 のフラットマップです。1 回の呼び出しで 20 credits を消費します。

注: 上流の 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：Web ページ URL（必須）
schema：フラットな Record<string, string> — フィールド名 → 指示（必須）
renderMode：none | basic | full
waitFor：ページ読み込み後の待機時間（ミリ秒、0–10000）
timeout：リクエストタイムアウト（ミリ秒、5000–120000）
apiKey：呼び出しごとの key 上書き

ベスト用途： リード生成、価格モニタリング、競合分析、データセット構築。 戻り値： スキーマのフィールド名をキーとするオブジェクトの data.data 配列。

3. Suggest Fields ツール (`thunderbit_suggest_fields`)

ページを分析し、抽出可能なフィールドを提案します。ページにどんなデータがあるか分からないときは最初にこれを使ってください。1 回の呼び出しで 1 credit を消費します。

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

Suggest Fields ツールのオプション

url：分析対象の Web ページ URL（必須）
prompt：AI へのオプションのステアリングヒント
countryCode：ISO 2 文字国コード（デフォルト：US）
apiKey：呼び出しごとの key 上書き

ベスト用途： extract 実行前のスキーマ発見、新しいスクレイピング対象のブートストラップ。 戻り値： { name, type, instruction } オブジェクトの配列。そのまま thunderbit_extract に渡せます。

4. Batch Distill Create (`thunderbit_batch_distill_create`)

最大 100 URL を蒸留に投入します。job ID が返るので、thunderbit_batch_distill_status で完了までポーリングします。1 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：1 ページあたりのリクエストタイムアウト（ミリ秒、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 始まりのページ index（デフォルト 0）
pageSize：1 ページあたりの結果数、1–100（デフォルト 20）
apiKey：呼び出しごとの key 上書き

ベスト用途： ポーリングと最終結果の取得。results が空になるまで page を増やし続けます。 戻り値： { id, status, total, completed, failed, creditsUsed, createdAt, completedAt, results: [{ index, url, success, markdown, error }, …] }。ジョブレベルの status は enum (PENDING / PROCESSING / COMPLETED / FAILED / CANCELLED)。各 URL ごとの結果項目は status ではなく boolean の success フィールドを使います。

6. Batch Extract Create (`thunderbit_batch_extract_create`)

共通スキーマで最大 100 URL を抽出に投入します。1 URL あたり 20 credits を消費します。

{
  "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：1 ページあたりのリクエストタイムアウト（ミリ秒、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 ごとのページ単位の抽出データを返します。

推奨ワークフロー

thunderbit_suggest_fields — ページが公開しているデータを確認
thunderbit_extract（または thunderbit_distill）— 単一 URL を取得
thunderbit_batch_*_create — 最大 100 URL に展開
thunderbit_batch_*_status — 終端までポーリング

エラーハンドリング

すべてのツールは構造化ヒント付きの 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 に起動ログを 1 行出します — ホストの MCP ログファイルを確認してください。

Cannot find module '@thunderbit/mcp-server'。 事前にインストールするか（npm install -g @thunderbit/mcp-server）、ホストのサンドボックスで npx のネットワークアクセスを許可してください。

初回実行で 401。 env ブロックはサーバーごとです — key が誤って別のサーバーエントリに入っていないか確認してください。原因の切り分けには、手動インストール経路でシェルに key を export して試すのが有効です。

バッチジョブが進まない。 MCP ツールは投入とポーリングしか行わず、ロングコネクションは保持しません。大規模バッチでは THUNDERBIT_TIMEOUT_MS を 180000 以上に上げるか、アプリ側で batch_*_create と webhook を組み合わせて投げっぱなしにしてください。

自作する

独自のツール構成（プロンプト、スコープ、フィルター、追加ツール）が欲しい場合は、MCP インテグレーションガイドを参照して @modelcontextprotocol/sdk でサーバーをゼロから構築してください。

オープンソース

@thunderbit/mcp-server は MIT ライセンスで GitHub にてオープンソース公開されています：thunderbit-open/thunderbit-mcp-server。

機能