MCP 서버

Model Context Protocol을 통해 Thunderbit API 사용하기 — 모든 MCP 호환 AI 호스트에서 검색, 스크래핑, 추출.

Thunderbit를 통합한 Model Context Protocol (MCP) 서버입니다. 페이지를 Markdown으로 디스틸하고, 자연어 지시로 모든 페이지에서 구조화된 필드를 추출하며, 한 번에 최대 100개의 URL을 처리하는 배치 작업을 실행합니다. GitHub에 오픈소스로 공개되어 있으며, npm에서 @thunderbit/mcp-server로 배포됩니다.

기능

모든 URL을 깔끔하고 LLM 친화적인 Markdown으로 디스틸
필드명 → 지시의 평탄한 맵으로 구조화 데이터 추출
suggest_fields로 추출 가능한 필드 자동 제안
최대 100개의 URL에 대해 배치 작업 실행 및 폴링 기반 상태 확인
멀티테넌트 Agent를 위한 호출별 API key 오버라이드
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자리 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 오버라이드

모든 도구는 THUNDERBIT_API_KEY를 오버라이드하는 선택적 apiKey 인자를 받습니다. 하나의 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: 페이지 로드 후 대기 시간(ms, 0–10000) — SPA에서는 늘리세요
includeTags: 포함할 HTML 태그(예: ["article", "main"])
excludeTags: 제외할 HTML 태그(예: ["nav", "footer"])
countryCode: ISO 2글자 국가 코드, 대문자(기본값: US)
timeout: 요청 타임아웃(ms, 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: 페이지 로드 후 대기 시간(ms, 0–10000)
timeout: 요청 타임아웃(ms, 5000–120000)
apiKey: 호출별 key 오버라이드

적합한 용도: 리드 생성, 가격 모니터링, 경쟁 분석, 데이터셋 구축. 반환: 스키마의 필드명을 키로 갖는 객체들의 data.data 배열.

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 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로 완료까지 폴링하세요. 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: 페이지당 요청 타임아웃(ms, 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 오버라이드

적합한 용도: 폴링 및 최종 결과 조회. results가 비워질 때까지 page를 늘리세요. 반환: { id, status, total, completed, failed, creditsUsed, createdAt, completedAt, results: [{ index, url, success, markdown, error }, …] }. job 단위 status는 enum (PENDING / PROCESSING / COMPLETED / FAILED / CANCELLED)이며, URL별 결과 항목은 status가 아니라 boolean success 필드를 사용합니다.

6. Batch Extract Create (`thunderbit_batch_extract_create`)

공통 스키마로 최대 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: 페이지당 요청 타임아웃(ms, 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에 시작 로그 한 줄을 출력합니다 — 호스트의 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과 결합해 fire-and-forget으로 처리하세요.

직접 만들기

별도의 도구 표면(다른 프롬프트, 스코프, 필터링, 추가 도구)이 필요하다면 @modelcontextprotocol/sdk로 처음부터 서버를 구축하는 MCP 통합 가이드를 참고하세요.

오픈소스

@thunderbit/mcp-server는 MIT 라이선스의 오픈소스로 GitHub에 공개되어 있습니다: thunderbit-open/thunderbit-mcp-server.

기능

설치