Cursor에서 웹 스크래핑
Cursor에 Spicrawl MCP 서버를 추가하세요. 그러면 에이전트가 웹 페이지를 깔끔한 Markdown으로 읽을 수 있습니다.
설정하기
세 단계로 Cursor의 에이전트에 도구, Spicrawl 코드를 작성하는 노하우, 둘을 쓰는 규칙을 갖춰 줍니다. 세 단계를 한 번에 하려면 spicrawl init --client cursor를 사용하세요.
Cursor가 시작되는 환경에 API 키를 설정하세요:
bashexport SPICRAWL_API_KEY=spicrawl_live_... # add to your shell profile, then restart CursormacOS에서는 Dock에서 시작한 앱이 셸 프로필을 보지 못합니다. 터미널에서
cursor .로 Cursor를 시작하세요..cursor/mcp.json(모든 프로젝트에는~/.cursor/mcp.json)에 서버를 추가하세요. Cursor가 키를 채워 주므로 파일을 커밋해도 안전합니다:.cursor/mcp.json{ "mcpServers": { "spicrawl": { "url": "https://mcp.spicrawl.com/mcp", "headers": { "Authorization": "Bearer ${env:SPICRAWL_API_KEY}" } } } }스킬을 설치하세요:
bashspicrawl skill install --client cursor # Without the CLI: mkdir -p .cursor/skills/spicrawl curl -fsSL https://app.spicrawl.com/skill.md -o .cursor/skills/spicrawl/SKILL.md이 규칙을
.cursor/rules/spicrawl.mdc로 저장하세요. 에이전트는 작업에 웹 데이터가 관련될 때 이를 읽습니다. 모든 채팅에 포함하려면alwaysApply: true로 설정하세요..cursor/rules/spicrawl.mdc--- description: Fetching, scraping or extracting data from web pages with Spicrawl alwaysApply: false --- # 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.Cursor Settings → MCP를 여세요.
spicrawl가 켜져 있고spicrawl_*도구 25개가 나열되는지 확인하세요.
먼저 해 볼 작업
Agent 모드에서 에이전트를 열고 다음과 같이 물어보세요:
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를 호출해야 합니다. 첫 결과가 비어 있을 때만 render: true를 추가해야 합니다.
클라우드 에이전트
Cursor의 클라우드 에이전트는 원격 VM에서 실행되므로 셸의 키를 볼 수 없습니다. Cursor 대시보드에서 URL https://mcp.spicrawl.com/mcp와 헤더 Authorization: Bearer에 키를 더해 서버를 추가하세요. 키는 커밋하지 마세요. 스킬과 규칙은 저장소에서 가져옵니다.
할 수 있는 일
이 서버는 에이전트에게 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 추출. 현재는 직접 프록시를 사용할 수 있습니다.
자주 묻는 질문
.cursor/mcp.json을 커밋해도 안전한가요?
Yes, if you use ${env:SPICRAWL_API_KEY} in the header. Cursor replaces it with the value from your environment, so the file holds no key.
서버에 401 오류가 표시되는 이유는 무엇인가요?
Cursor가 시작될 때 SPICRAWL_API_KEY가 설정되어 있지 않았습니다. macOS에서 Dock으로 시작한 앱은 셸 프로필을 읽지 못합니다. 대신 터미널에서 cursor . 로 Cursor를 시작하세요.
Cursor 클라우드 에이전트에서도 작동하나요?
예. Cursor 대시보드에서 URL과 Authorization 헤더로 서버를 추가하세요. 키는 커밋하지 마세요. 스킬과 규칙은 저장소에서 읽습니다.
서버가 목록에는 있는데 도구가 없습니다. 어떻게 해야 하나요?
Cursor Settings → MCP에서 껐다가 다시 켠 다음 새 채팅을 여세요.
페이지당 비용이 얼마인가요?
일반 fetch는 1 크레딧, JavaScript 렌더링은 3, 풀 브라우저 렌더링은 8입니다. 실패한 요청은 0 크레딧입니다. 캐시 적중은 그 결과를 저장한 fetch와 같은 비용이 듭니다. 에이전트가 예상보다 많이 쓰지 않도록 요청마다 max_cost를 설정하게 하세요.