이제 Spicrawl은 OpenAI Agents SDK, LangChain, Codex, Claude Code 등과 함께 작동합니다.통합 보기
본문으로 건너뛰기

Claude Code에서 웹 스크래핑

Claude Code에 Spicrawl MCP 서버를 추가하세요. 그러면 Claude가 웹 페이지를 깔끔한 Markdown으로 읽을 수 있습니다.

설정하기

세 단계로 Claude Code에 도구, Spicrawl 코드를 작성하는 노하우, 둘을 쓰는 규칙을 갖춰 줍니다. 세 단계를 한 번에 하려면 spicrawl init --client claude를 사용하세요.

  1. API 키를 설정하세요:

    bash
    export SPICRAWL_API_KEY=spicrawl_live_...   # add to your shell profile
  2. MCP 서버를 추가하세요. 셸이 키를 채워 주고 Claude Code가 이를 저장소 밖의 ~/.claude.json에 저장합니다. 모든 프로젝트에서 쓰려면 --scope user를 추가하세요.

    bash
    claude mcp add --transport http spicrawl https://mcp.spicrawl.com/mcp \
      --header "Authorization: Bearer $SPICRAWL_API_KEY"

    팀이라면 대신 프로젝트 루트에 .mcp.json를 커밋하세요. Claude Code는 각자의 환경에서 본인의 키를 읽습니다:

    .mcp.json
    {
      "mcpServers": {
        "spicrawl": {
          "type": "http",
          "url": "https://mcp.spicrawl.com/mcp",
          "headers": { "Authorization": "Bearer ${SPICRAWL_API_KEY}" }
        }
      }
    }
  3. 스킬을 설치하세요. Claude는 작업에 웹 데이터가 관련되거나 /spicrawl를 입력하면 이를 불러옵니다:

    bash
    mkdir -p .claude/skills/spicrawl
    curl -fsSL https://app.spicrawl.com/skill.md -o .claude/skills/spicrawl/SKILL.md
  4. 프로젝트 루트의 CLAUDE.md에 이 섹션을 붙여 넣으세요:

    CLAUDE.md
    ## Web data (Spicrawl)
    
    Use Spicrawl to read web pages: the spicrawl_* MCP tools in chat, or
    POST https://api.spicrawl.com/v1/scrape with `Authorization: Bearer $SPICRAWL_API_KEY` in code.
    Docs: https://docs.spicrawl.com/llms.txt (append .md to any page URL for Markdown).
    
    - Ask for markdown: `response_format: "markdown"` (API default is html); on spicrawl_scrape, `format: "markdown"`.
    - Check the site's status, not only the HTTP status: `X-Target-Status` header, or `status`
      in the JSON envelope (spicrawl_scrape with `format: "json"`). 200 is the page; 404/410
      mean it does not exist; 403/429/503 mean the site refused, so escalate.
    - On an error, switch on `code`. Retry only when `retryable` is true, after
      `retry_after_seconds`. Read `diagnostics.hint` and change what it names first.
      Never retry ERR::REQUEST::*, ERR::AUTH::* or ERR::LIMIT::QUOTA_EXCEEDED.
    - Escalate one step at a time and stop at the first that works:
      plain fetch (1 credit) -> `js_render: true` (3) -> add the user's own `proxy`
      if they have one. Empty or skeleton content means render; ERR::UPSTREAM::CHALLENGE
      or a 403 target status means retry once, then the user's own proxy.
    - Set `max_cost` on every request to the price of the step you intend.
    - Keep the cache on (default). Set `cache: false` only for prices, stock or other live data.
    - Trim tokens with `main_content_only` (on by default for markdown), `include_tags`, `exclude_tags`.
    - For more than 20 URLs, use a batch job (spicrawl_batch_submit / POST /v1/batch).
      Batch items return html, markdown or text (spicrawl_batch_submit defaults to markdown,
      POST /v1/batch to html). Extraction, screenshots, actions and sessions are refused
      with a 400 before anything is charged: scrape those URLs one by one.
    - Never print or commit SPICRAWL_API_KEY. Log `X-Request-Id` for failures.
  5. claude mcp list 또는 세션에서 /mcp로 확인하세요. spicrawl_* 도구 25개가 보여야 합니다.

플러그인을 쓰고 싶으신가요? MCP 서버와 스킬이 함께 들어 있어 2단계와 3단계를 건너뛸 수 있습니다. Claude Code는 플러그인을 켤 때 키를 물어봅니다:

bash
claude plugin marketplace add OfficialSpicrawl/agent-plugins
claude plugin install spicrawl@spicrawl-plugins

먼저 해 볼 작업

프로젝트에서 claude를 시작하고 물어보세요:

prompt
Use Spicrawl to read https://example.com/pricing as markdown. List each plan with its monthly price.
If the page comes back empty, retry with rendering. Tell me how many credits it cost.

Claude가 spicrawl_scrape를 호출합니다. 비용을 보고하려면 format: "json"가 필요한데, 그 엔벨로프에 credits가 들어 있기 때문입니다. 전체 안내는 Claude Code로 웹사이트를 스크랩하는 방법에 있습니다.

할 수 있는 일

이 서버는 에이전트에게 spicrawl_* 도구 25개를 제공합니다. 각 호출은 API를 직접 호출할 때와 같은 한도와 크레딧으로 사용자의 API 키로 실행됩니다.

  • 페이지 하나 읽기: spicrawl_scrape는 Markdown(기본값), 텍스트, HTML, JSON 또는 PDF를 반환합니다.
  • 여러 페이지 읽기: spicrawl_batch_submit는 최대 10,000개의 URL을 대기열에 넣습니다. 이어서 spicrawl_batch_status와 spicrawl_batch_results를 사용하세요.
  • 로그인이 필요한 페이지: spicrawl_session_create는 호출 사이에 쿠키와 스토리지를 유지합니다.
  • 실패 디버깅: spicrawl_requests_list와 spicrawl_request_get.
  • 사용량 확인: spicrawl_usage_summary 및 기타 사용량 도구입니다. 이 도구에는 read 범위가 있는 키가 필요합니다.
  • 조회하기: spicrawl_docs_search와 spicrawl_docs_read로 Spicrawl 문서를 검색하고 읽습니다.

도구 하나, spicrawl_browser_connect_url는 목록에 있지만 곧 제공될 예정입니다. spicrawl_scrape에서 렌더링 인수는 API의 js_render가 아니라 render입니다.

알아 두세요

  • 크롤링은 지원하지 않습니다. Spicrawl은 링크를 따라가거나 페이지를 찾지 않습니다. 에이전트에게 URL을 주세요.
  • 요청당 크레딧. 일반 fetch는 1 크레딧, JavaScript 렌더링은 3, 전체 브라우저 렌더링은 8입니다.
  • 실패는 무료입니다. 실패한 요청은 0 크레딧입니다.
  • 캐시는 시간을 절약해 줄 뿐 크레딧을 절약해 주지는 않습니다. 캐시 적중 비용은 그 결과를 저장한 요청과 같습니다.
  • 호출마다 상한을 두세요. max_cost를 설정하면 더 많은 비용이 들 수 있는 요청은 실행 전에 거부됩니다.
  • 곧 제공 예정: 관리형 프록시, 스텔스 모드, 원격 브라우저, 일반 문장 프롬프트를 이용한 AI 추출. 현재는 직접 프록시를 사용할 수 있습니다.

자주 묻는 질문

Claude Code에 Spicrawl을 어떻게 추가하나요?

SPICRAWL_API_KEY를 export한 다음 claude mcp add --transport http spicrawl https://mcp.spicrawl.com/mcp --header "Authorization: Bearer $SPICRAWL_API_KEY"를 실행하세요. claude mcp list로 확인하세요.

설정을 팀과 공유하려면 어떻게 하나요?

Commit .mcp.json at the project root with the header "Bearer ${SPICRAWL_API_KEY}". Claude Code fills in each person’s own key from their environment when it starts.

Claude Code 플러그인이 있나요?

예. claude plugin marketplace add OfficialSpicrawl/agent-plugins를 실행한 다음 claude plugin install spicrawl@spicrawl-plugins를 실행하세요. MCP 서버와 스킬이 함께 들어 있으며, 켤 때 키를 물어봅니다.

Claude가 js_render에 대해 "unknown argument" 오류를 내는 이유는 무엇인가요?

spicrawl_scrape 도구에서는 인수 이름이 render입니다. js_render는 HTTP API에서 쓰는 이름입니다.

페이지당 비용이 얼마인가요?

일반 fetch는 1 크레딧, JavaScript 렌더링은 3, 풀 브라우저 렌더링은 8입니다. 실패한 요청은 0 크레딧입니다. 캐시 적중은 그 결과를 저장한 fetch와 같은 비용이 듭니다. 에이전트가 예상보다 많이 쓰지 않도록 요청마다 max_cost를 설정하게 하세요.