Web scraping in Cursor
Aggiungi il server MCP di Spicrawl a Cursor. Il suo agente potrà così leggere le pagine web come Markdown pulito.
Configuralo
Tre passaggi danno all’agente di Cursor gli strumenti, il know-how per scrivere codice Spicrawl e le regole per usarli entrambi. Oppure fai tutti e tre con spicrawl init --client cursor.
Imposta la tua chiave API nell’ambiente da cui parte Cursor:
bashexport SPICRAWL_API_KEY=spicrawl_live_... # add to your shell profile, then restart CursorSu macOS, le app avviate dal Dock non vedono il profilo della tua shell. Avvia Cursor da un terminale con
cursor ..Aggiungi il server a
.cursor/mcp.json(o~/.cursor/mcp.jsonper ogni progetto). Cursor inserisce la chiave, quindi il file si può committare senza rischi:.cursor/mcp.json{ "mcpServers": { "spicrawl": { "url": "https://mcp.spicrawl.com/mcp", "headers": { "Authorization": "Bearer ${env:SPICRAWL_API_KEY}" } } } }Installa la skill:
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.mdSalva questa regola come
.cursor/rules/spicrawl.mdc. L’agente la legge quando un’attività riguarda dati web. ImpostaalwaysApply: trueper includerla in ogni chat..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.Apri Cursor Settings → MCP. Controlla che
spicrawlsia attivo e che elenchi 25 strumentispicrawl_*.
Un primo task da provare
Apri l’agente in modalità Agent e chiedi:
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.L’agente dovrebbe richiamare spicrawl_scrape con format: "markdown". Dovrebbe aggiungere render: true solo se il primo risultato è vuoto.
Agenti cloud
Gli agenti cloud di Cursor girano in una VM remota, quindi non vedono la chiave della tua shell. Aggiungi il server nella dashboard di Cursor con l’URL https://mcp.spicrawl.com/mcp e l’header Authorization: Bearer più la tua chiave. Non committare la chiave. La skill e la regola arrivano dal repository.
Cosa può fare
Il server offre all’agente 25 strumenti spicrawl_*. Ogni chiamata viene eseguita con la tua chiave API, con gli stessi limiti e crediti di una chiamata diretta all’API.
- Leggi una pagina:
spicrawl_scraperestituisce Markdown (predefinito), testo, HTML, JSON o PDF. - Leggi molte pagine:
spicrawl_batch_submitmette in coda fino a 10.000 URL. Poi usaspicrawl_batch_statusespicrawl_batch_results. - Pagine dietro un login:
spicrawl_session_createmantiene cookie e storage tra una chiamata e l’altra. - Fai il debug di un errore:
spicrawl_requests_listespicrawl_request_get. - Controlla l’utilizzo:
spicrawl_usage_summarye gli altri strumenti di utilizzo. Richiedono una chiave con lo scoperead. - Cerca informazioni:
spicrawl_docs_searchespicrawl_docs_readcercano e leggono nella documentazione di Spicrawl.
Uno strumento, spicrawl_browser_connect_url, è elencato ma in arrivo. Su spicrawl_scrape, l’argomento di rendering è render, non js_render come nell’API.
Da sapere
- Nessun crawling. Spicrawl non segue link né trova pagine. Dai all’agente gli URL.
- Crediti per richiesta. Un fetch semplice costa 1 credito. Il rendering JavaScript 3. Il rendering con browser completo 8.
- I fallimenti sono gratuiti. Una richiesta fallita costa 0 crediti.
- La cache fa risparmiare tempo, non crediti. La cache fa risparmiare tempo, non crediti.
- Limita ogni chiamata. Imposta
max_cost, e una richiesta che potrebbe costare di più viene rifiutata prima di essere eseguita. - In arrivo: proxy gestiti, modalità stealth, un browser remoto ed estrazione con AI da un prompt in linguaggio naturale. Oggi puoi usare il tuo proxy.
Domande frequenti
È sicuro fare commit di .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.
Perché il server mostra un errore 401?
SPICRAWL_API_KEY non era impostata quando Cursor è stato avviato. Su macOS, le app avviate dal Dock non vedono il profilo della tua shell. Avvia invece Cursor da un terminale con cursor .
Funziona con gli agenti cloud di Cursor?
Sì. Aggiungi il server nella dashboard di Cursor con l’URL e il tuo header Authorization. Non fare commit della chiave. La skill e la regola vengono lette dal repository.
Il server è elencato ma non ha tool. E adesso?
Disattivalo e riattivalo in Cursor Settings → MCP, poi apri una nuova chat.
Quanto costa ogni pagina?
Un fetch semplice costa 1 credito, il rendering JavaScript 3 e il rendering con browser completo 8. Le richieste fallite costano 0. Un cache hit costa quanto il fetch che l’ha salvato. Chiedi all’agente di impostare max_cost su ogni richiesta così non spende mai più del previsto.