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

Gemini CLI에서 웹 스크래핑

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

설정하기

spicrawl init는 Gemini CLI를 지원하지 않으므로 다음 단계를 따르세요.

  1. 키를 설정한 다음 두 번째 이름으로 복사하세요:

    bash
    export SPICRAWL_API_KEY=spicrawl_live_...   # add to your shell profile
    export SPICRAWL_MCP_BEARER="$SPICRAWL_API_KEY"

    Gemini CLI는 헤더를 채우기 전에 이름에 KEY, TOKEN, AUTH 등이 들어간 변수를 제거합니다. 그래서 $SPICRAWL_API_KEY는 비어 있게 되고 서버는 401로 응답합니다.

  2. ~/.gemini/settings.json(프로젝트 하나에는 .gemini/settings.json)에 서버를 추가하세요. url 대신 httpUrl를 사용하세요:

    ~/.gemini/settings.json
    {
      "mcpServers": {
        "spicrawl": {
          "httpUrl": "https://mcp.spicrawl.com/mcp",
          "headers": { "Authorization": "Bearer $SPICRAWL_MCP_BEARER" }
        }
      }
    }

    또는 명령줄에서 같은 항목을 추가하세요. 작은따옴표를 쓰면 변수 참조가 파일에 그대로 남습니다:

    bash
    gemini mcp add --scope user --transport http \
      --header 'Authorization: Bearer $SPICRAWL_MCP_BEARER' \
      spicrawl https://mcp.spicrawl.com/mcp
  3. 스킬을 설치한 뒤 실행 중인 세션에서 /skills reload를 실행하세요:

    bash
    spicrawl skill install --client codex
    
    # Without the CLI:
    mkdir -p .agents/skills/spicrawl
    curl -fsSL https://app.spicrawl.com/skill.md -o .agents/skills/spicrawl/SKILL.md
  4. 프로젝트 루트의 GEMINI.md에 이 섹션을 붙여 넣은 뒤 /memory reload를 실행하세요:

    GEMINI.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. gemini를 시작하고 /mcp를 실행하세요. spicrawl가 spicrawl_* 도구 25개와 함께 연결되어 있어야 합니다.

먼저 해 볼 작업

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

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.

에이전트는 format: "markdown"로 spicrawl_scrape를 호출해야 합니다. Gemini CLI는 서버에 "trust": true가 없으면 도구를 호출할 때마다 확인을 요청합니다.

할 수 있는 일

이 서버는 에이전트에게 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 추출. 현재는 직접 프록시를 사용할 수 있습니다.

자주 묻는 질문

헤더에 SPICRAWL_API_KEY를 그대로 쓰면 안 되는 이유는 무엇인가요?

Gemini CLI는 헤더를 확장하기 전에 이름에 KEY, TOKEN, AUTH 등이 들어 있는 변수를 제거합니다. $SPICRAWL_API_KEY는 비어 있게 되고 서버는 401로 응답합니다. SPICRAWL_MCP_BEARER를 사용하세요.

spicrawl init은 Gemini CLI를 지원하나요?

아니요. 이 페이지의 수동 단계를 따라 하세요.

url과 httpUrl 중 무엇을 써야 하나요?

httpUrl을 사용하세요. Gemini CLI에서 url은 SSE를 의미하는데, Spicrawl 서버는 Streamable HTTP를 사용합니다.

Gemini CLI용 Spicrawl 확장이 있나요?

아니요. 게시된 Spicrawl 확장은 없으므로 설정 항목을 사용하세요.

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

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