Spicrawl

Servidor MCP Spicrawl

O servidor MCP Spicrawl é um servidor do Model Context Protocol que dá a agentes de IA no Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Gemini CLI e Codex recursos de raspagem web para Markdown, extração estruturada de dados, capturas de tela, sessões de navegador e raspagem em lote como ferramentas nativas.

Documentação · Obtenha uma chave de API · SDK TypeScript · CLI · Plugins de agente · Changelog

Início rápido

1. Crie uma chave de API em app.spicrawl.com. As chaves começam com spicrawl_live_ ou spicrawl_test_.

2. Conecte o endpoint hospedado, https://mcp.spicrawl.com/mcp (MCP Streamable HTTP, nada para instalar):

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

   Codex: codex mcp add spicrawl --url https://mcp.spicrawl.com/mcp --bearer-token-env-var SPICRAWL_API_KEY

3. Ou execute-o localmente via stdio (Node.js 20+), para clientes que só iniciam servidores locais:

   claude mcp add spicrawl --env SPICRAWL_API_KEY=$SPICRAWL_API_KEY -- npx -y @spicrawl/mcp
   

4. Pergunte ao seu agente: "Use o Spicrawl para ler https://example.com/pricing como markdown e liste cada plano com seu preço." Ele chama spicrawl_scrape e recebe a página de volta como Markdown.

Ambos os transportes servem as mesmas ferramentas spicrawl_* (25 são definidas; o endpoint hospedado lista 24 até os navegadores remotos serem lançados, veja Ferramentas), e cada chamada é executada sob sua chave com os mesmos escopos, limites e créditos de uma chamada direta à API.

O que ele faz

• Raspe qualquer URL para Markdown, texto, HTML, um envelope JSON ou um PDF impresso com uma ferramenta, spicrawl_scrape. Markdown é o padrão e reduz a página ao seu conteúdo principal.
• Renderize JavaScript com render: true (3 créditos). Um fetch simples custa 1 crédito, capturas de tela, PDFs e actions usam um navegador completo (8 créditos), e mode: "auto" escala de fetch para navegador e cobra apenas o nível que funcionou (tabela de preços). Você nunca escolhe a renderização; o Spicrawl escolhe a mais barata que pode fazer o que a solicitação pede.
• Extraia dados estruturados com um mapa de seletores CSS/XPath (extract) ou a partir do JSON-LD, OpenGraph, Twitter Card e microdados que uma página publica (autoparse).
• Controle a página antes da captura com 8 ações de navegador tipadas: click, fill, wait_for, wait_for_navigation, scroll (incluindo rolagem infinita), select, evaluate e screenshot.
• Retorne capturas de tela e PDFs que o modelo pode ver: capturas de tela chegam como blocos de imagem MCP (até 5 MB de base64 cada) e páginas impressas como blocos de recurso application/pdf (até 10 MB).
• Raspe milhares de URLs em lote como um único trabalho assíncrono, até 10.000 itens por chamada, com 9 ferramentas para enviar, consultar, paginar resultados, tentar novamente, cancelar e manter um trabalho aberto para rastreamento.
• Mantenha um navegador conectado com sessões persistentes: cookies, armazenamento e um nível de renderização fixo reutilizados entre raspagens.
• Responda "quanto isso custou?" a partir de ferramentas de uso e registro de solicitações, e leia a documentação do Spicrawl de dentro do agente.

Qual ferramenta usar

• Se você precisa do conteúdo ou dados de uma página agora, use spicrawl_scrape.
• Se a página estiver em branco ou for um esqueleto sem JavaScript, chame spicrawl_scrape novamente com render: true.
• Se você conhece a estrutura da página, use extract com seletores CSS; se não conhece, tente autoparse.
• Se você tem mais de cerca de 20 URLs, use spicrawl_batch_submit, depois spicrawl_batch_status e spicrawl_batch_results.
• Se você descobre URLs conforme avança (rastreamento), envie com open: true, acrescente com spicrawl_batch_add_items e finalize com spicrawl_batch_close.
• Se você precisa fazer login primeiro, use spicrawl_session_create e passe seu id como session_id para spicrawl_scrape.
• Se uma chamada falhou e você precisa saber o motivo, use spicrawl_request_get com o id da solicitação, ou spicrawl_requests_list com only_errors.
• Se você não tem certeza de um parâmetro ou código de erro, use spicrawl_docs_search antes de adivinhar.

Ferramentas

25 ferramentas, agrupadas por tarefa. O endpoint hospedado lista 24 até os navegadores remotos serem lançados: seu tools/list sem chave e o cartão do servidor deixam de fora spicrawl_browser_connect_url (Em breve), enquanto uma sessão aberta com sua chave e o pacote stdio (npx -y @spicrawl/mcp) lista todas as 25. As ferramentas rejeitam argumentos desconhecidos, então um campo com erro de digitação falha com um erro que o nomeia em vez de ser silenciosamente ignorado. Cada ferramenta define um title e anotações explícitas de readOnlyHint, destructiveHint e openWorldHint, para que um cliente saiba quais chamadas confirmar: spicrawl_scrape não é somente leitura (seus method e actions podem enviar formulários), e spicrawl_batch_cancel, spicrawl_session_release e spicrawl_session_delete são destrutivas. Cada ferramenta também declara um outputSchema e retorna structuredContent correspondentes ao lado do mesmo texto que sempre retornou, para que um cliente possa ler campos (credits, status, next_cursor, ...) sem analisar texto. Os esquemas listam o que um agente pode usar com segurança e permanecem abertos: campos que a API adicionar depois passam direto, e status e níveis são strings simples. Uma ferramenta que retorna um documento ou um array JSON (spicrawl_docs_read, spicrawl_batch_task_content) o coloca sob content em structuredContent. Referência completa de argumentos: docs.spicrawl.com/agents/mcp.

Raspe um site para Markdown

Raspe muitas URLs em lote

Sessões de navegador

Uso e histórico de solicitações

Documentação

Em breve

spicrawl_browser_connect_url vai cunhar uma URL WebSocket CDP de uso único para controlar um navegador hospedado pelo Spicrawl a partir de qualquer cliente CDP; navegadores remotos ainda não estão disponíveis. É a 25ª ferramenta e a única que a listagem hospedada sem chave e o cartão do servidor deixam de fora (24 ferramentas lá). Os esquemas também aceitam ai_extract, stealth, extract_preset, premium_proxy, proxy_country e sticky_key antes do lançamento. Os agentes ainda não devem enviá-los. Para listar apenas o que funciona hoje, defina SPICRAWL_MCP_HIDE_UNAVAILABLE=1 (veja Variáveis de ambiente).

Exemplos de prompts

• "Raspe https://example.com/pricing como markdown e resuma os planos."
• "Obtenha o nome do produto, preço e status de estoque desta URL." (spicrawl_scrape com extract ou autoparse)
• "Tire uma captura de tela de página inteira de https://example.com depois que o banner de cookies desaparecer." (render, actions, screenshot_fullpage)
• "Raspe estas 500 URLs e me dê o título de cada página." (spicrawl_batch_submit, depois spicrawl_batch_results)
• "Por que minha última raspagem falhou?" (spicrawl_requests_list com only_errors, depois spicrawl_request_get)
• "Quantos créditos usei este mês?" (spicrawl_usage_summary)

Configure seu cliente MCP

Coloque sua chave em SPICRAWL_API_KEY e referencie-a a partir da configuração onde o cliente permitir, para que a chave nunca caia em um arquivo versionado.

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

{
  "mcpServers": {
    "spicrawl": {
      "type": "http",
      "url": "https://mcp.spicrawl.com/mcp",
      "headers": { "Authorization": "Bearer ${SPICRAWL_API_KEY}" }
    }
  }
}

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

{
  "mcpServers": {
    "spicrawl": {
      "command": "npx",
      "args": ["-y", "@spicrawl/mcp"],
      "env": { "SPICRAWL_API_KEY": "spicrawl_live_..." }
    }
  }
}

{
  "mcpServers": {
    "spicrawl": {
      "url": "https://mcp.spicrawl.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SPICRAWL_API_KEY}" }
    }
  }
}

{
  "inputs": [
    { "type": "promptString", "id": "spicrawl-api-key", "description": "Spicrawl API key", "password": true }
  ],
  "servers": {
    "spicrawl": {
      "type": "http",
      "url": "https://mcp.spicrawl.com/mcp",
      "headers": { "Authorization": "Bearer ${input:spicrawl-api-key}" }
    }
  }
}

devin mcp add spicrawl https://mcp.spicrawl.com/mcp -H "Authorization: Bearer $SPICRAWL_API_KEY"

{
  "mcpServers": {
    "spicrawl": {
      "serverUrl": "https://mcp.spicrawl.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SPICRAWL_API_KEY}" }
    }
  }
}

export SPICRAWL_MCP_BEARER="$SPICRAWL_API_KEY"

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

codex mcp add spicrawl --url https://mcp.spicrawl.com/mcp --bearer-token-env-var SPICRAWL_API_KEY

[mcp_servers.spicrawl]
url = "https://mcp.spicrawl.com/mcp"
bearer_token_env_var = "SPICRAWL_API_KEY"

[mcp_servers.spicrawl]
command = "npx"
args = ["-y", "@spicrawl/mcp"]
env = { SPICRAWL_API_KEY = "spicrawl_live_..." }

Variáveis de ambiente

Sem nenhuma variável de docs definida, um servidor apontado para uma API auto-hospedada lê a documentação dessa própria API em <SPICRAWL_PUBLIC_BASE_URL or SPICRAWL_BASE_URL>/docs.

Auto-hospede o servidor MCP via HTTP

O endpoint hospedado executa o servidor Streamable HTTP deste pacote. Para executar o seu próprio:

SPICRAWL_MCP_ADDR=127.0.0.1:8090 \
SPICRAWL_BASE_URL=https://api.spicrawl.com \
npx -y @spicrawl/mcp --http

• SPICRAWL_BASE_URL padrão é http://127.0.0.1:8080 no modo HTTP (uma API Spicrawl no mesmo host), não a API pública. Defina-a como https://api.spicrawl.com para servir a API pública.
• O MCP é servido em POST/GET/DELETE /mcp; liveness em GET /healthz (sem autenticação).
• GET /.well-known/mcp/server-card.json (sem autenticação, Cache-Control: public, max-age=3600) é um cartão de servidor estático para diretórios como Smithery que não conseguem escanear /mcp sem chave: serverInfo, o transporte, autenticação bearer e a lista de ferramentas. As ferramentas são lidas das mesmas definições de tools/list, como se SPICRAWL_MCP_HIDE_UNAVAILABLE estivesse ligado: 24 ferramentas, sem spicrawl_browser_connect_url. Uma sessão aberta com chave lista essa ferramenta também, a menos que a variável esteja definida.
• Sem nenhuma chave, /mcp responde apenas descoberta: initialize, ping, a notificação initialized e tools/list (a mesma lista de 24 ferramentas do cartão do servidor; nenhum Mcp-Session-Id é emitido e nada é enviado upstream). Qualquer outra solicitação, incluindo um tools/call, é 401, assim como uma solicitação que envia uma chave malformada ou nomeia uma sessão. Um GET sem sessão é 405.
• Cada chamador envia sua própria chave como Authorization: Bearer spicrawl_live_..., ou, para um gateway que não consegue enviar o prefixo Bearer , como um cabeçalho bruto Authorization: spicrawl_live_..., x-api-key ou api-key (veja "Smithery e outros gateways" acima; nunca um parâmetro de consulta). A chave é verificada contra a API antes de uma sessão abrir (401 se recusada, 503 com Retry-After se a API não puder ser alcançada), e uma sessão é fixada à chave que a abriu.
• O servidor fala HTTP simples. Coloque-o atrás de TLS antes de enviar chaves por uma rede.

Endpoint ChatGPT (OAuth)

O mesmo processo pode servir um segundo endpoint MCP restrito para aplicativos ChatGPT. Ele fica desligado a menos que SPICRAWL_CHATGPT_ENABLED esteja ligado, e /mcp não muda de qualquer forma.

A autenticação aceita apenas tokens de acesso OAuth (spicrawl_oat_…):

• Sem token: 401 com WWW-Authenticate: Bearer resource_metadata="https://mcp.spicrawl.com/.well-known/oauth-protected-resource/chatgpt/mcp", scope="scrape batch".
• Um token ruim, inativo, expirado ou com audiência errada, ou uma chave de API (spicrawl_live_…/spicrawl_test_…, nunca aceita aqui): o mesmo 401 mais error="invalid_token", error_description="…".
• Uma chamada de ferramenta que os escopos do token não cobrem: 403 com error="insufficient_scope". spicrawl_scrape precisa de scrape, as ferramentas em lote precisam de batch, as ferramentas de docs precisam apenas de um token válido.
• Servidor de autorização inacessível ou recusando o segredo deste servidor: 503 com Retry-After.

Cada token é verificado com POST <issuer>/api/oauth/introspect (Authorization: Bearer <SPICRAWL_OAUTH_INTROSPECT_SECRET>, corpo de formulário token=…). Apenas active: true com aud igual ao recurso é aceito. Uma resposta positiva é armazenada em cache pelo SHA-256 do token por no máximo 30 segundos e nunca além de seu exp. As ferramentas executam upstream sob o api_key que a introspecção retorna; nem ele nem o token são registrados. Se a API recusar essa chave no meio de uma chamada, a ferramenta retorna um erro cujo _meta["mcp/www_authenticate"] carrega um novo desafio invalid_token, e o token é removido do cache.

O endpoint lista seis ferramentas, cada uma com readOnlyHint/destructiveHint/openWorldHint explícitos, um título e securitySchemes: [{type: "oauth2", scopes: [...]}] (também em _meta.securitySchemes):

spicrawl_scrape é somente leitura aqui, ao contrário de /mcp: este endpoint apenas envia um GET, sem method, corpo, cabeçalhos ou actions. spicrawl_batch_submit não é somente leitura, pois cria um job.

spicrawl_batch_results preenche o conteúdo de um item bem-sucedido que a página de resultados lista sem ele, o que acontece enquanto o job ainda está finalizando, a partir de GET /v1/batch/{id}/tasks/{seq}/content. Ele busca no máximo 25 itens e 2 MiB por página. Um item que ainda não pode ser lido retorna unavailable, e um que exceda o limite de tamanho retorna omitted.

Todos os outros argumentos são recusados, não descartados. Os resultados mantêm o conteúdo, o status do site e os créditos cobrados; ids de requisição, timestamps, detalhes de engine e proxy, referências de armazenamento e ids de projeto são omitidos.

Instalado globalmente (npm install -g @spicrawl/mcp), o comando é spicrawl-mcp (alias spicrawl-mcp-server), com --http, --version e --help.

FAQ

Existe um servidor MCP Spicrawl hospedado?

Sim: https://mcp.spicrawl.com/mcp, MCP Streamable HTTP, autenticado com Authorization: Bearer <API key>, então não há nada para instalar.

O Spicrawl é gratuito?

O Spicrawl cobra créditos por requisição bem-sucedida, e durante o beta toda organização recebe um plano de 1.000 créditos por mês. Requisições com falha custam 0 créditos; um cache hit é cobrado pelo mesmo preço do fetch que o armazenou. Veja Créditos.

Ele renderiza JavaScript?

Sim. Defina render: true em spicrawl_scrape para executar a página em um navegador, ou mode: "auto" para deixar o Spicrawl escalar de um fetch simples somente quando necessário. Não há argumento para escolher a renderização em spicrawl_scrape ou nas ferramentas de lote: o Spicrawl escolhe para cada requisição e cobra o nível que atendeu (fetch, js ou browser, reportado como engine no resultado JSON).

Funciona com Claude Code, Cursor e VS Code?

Sim, e também com Claude Desktop, Windsurf, Gemini CLI, Codex e qualquer cliente que fale MCP Streamable HTTP com cabeçalhos personalizados ou que inicie servidores stdio.

Ele pode rastrear um site inteiro?

Não existe uma ferramenta única de rastreamento. Raspe uma página com links: true para obter seus links e depois alimente-os em um job de lote aberto (open: true e spicrawl_batch_add_items).

Ele suporta OAuth?

Não em /mcp: ele aceita apenas chaves de API do Spicrawl, então desative o OAuth para ele em clientes que tentam usá-lo em um 401. O endpoint separado do ChatGPT em /chatgpt/mcp aceita apenas tokens de acesso OAuth, quando o operador o ativa.

Devo usar o servidor MCP, o SDK ou o CLI?

Use o servidor MCP quando um agente de IA deve chamar o Spicrawl como ferramentas. Use @spicrawl/sdk no seu próprio código TypeScript ou JavaScript, @spicrawl/cli em um terminal ou script de shell, e a API REST em qualquer outra linguagem.

Solução de problemas

curl -i https://mcp.spicrawl.com/mcp sem uma chave responde 401: o endpoint está acessível.

Pacotes relacionados

• @spicrawl/sdk: o SDK oficial em TypeScript para a API do Spicrawl.
• @spicrawl/cli: a interface de linha de comando do Spicrawl.
• OfficialSpicrawl/agent-plugins: plugins que agrupam este servidor e a habilidade Spicrawl para Claude Code, Codex, Cursor, Gemini CLI e mais.

Links

• Documentação: docs.spicrawl.com/agents/mcp
• Documentação para LLMs: docs.spicrawl.com/llms.txt
• Painel e chaves de API: app.spicrawl.com
• Problemas: github.com/OfficialSpicrawl/mcp/issues
• Segurança: SECURITY.md. Nunca faça commit de uma chave de API; revogue uma chave vazada em app.spicrawl.com.

Publicação no Registro MCP

server.json lista tanto o pacote npm/stdio quanto o endpoint hospedado Streamable HTTP sob io.github.OfficialSpicrawl/mcp. As chaves de API são solicitadas à pessoa que instala o servidor; nenhuma chave pertence ao manifesto.

O fluxo de trabalho existente release publica no Registro MCP após o sucesso do job npm, em pushes para main ou execuções manuais a partir de main. A autenticação do registro usa GitHub OIDC (id-token: write), então não precisa de novo segredo, login de dispositivo ou registro DNS. O lançamento npm continua usando o segredo existente NPM_TOKEN.

Para um lançamento, execute npm version --no-git-tag-version X.Y.Z, atualize o changelog e envie as alterações para main. O hook de versão npm sincroniza ambas as versões em server.json. Se você editar package.json manualmente, execute npm run registry:sync. O CI verifica o manifesto contra o $schema oficial com Ajv e rejeita desvios de nome ou versão antes da publicação npm. Para executar essa verificação localmente:

npm ci
npm run registry:validate
# Offline: pass a downloaded copy of the exact server.json $schema URL.
npm run registry:validate -- /path/to/server.schema.json

O job do registro verifica se o pacote npm publicado tem o mcpName correspondente antes de publicar. Uma versão existente do registro é ignorada; falhas de consulta interrompem o job. Para tentar novamente uma falha do registro ou listar a versão npm atual já publicada, execute o fluxo de trabalho release em main novamente. Use uma nova versão para alterações de metadados em uma listagem existente. O binário do publicador é fixado e seu download é verificado contra os checksums do lançamento; atualize sua versão em release.yml ao atualizar o CLI.

Verifique a publicação em https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.OfficialSpicrawl/mcp. O fluxo de trabalho deve ser mesclado em OfficialSpicrawl/mcp antes que o OIDC possa publicar esse namespace. Pull requests de forks validam e testam, mas nunca executam o job do registro.

Referências oficiais: início rápido de publicação, GitHub Actions, e servidores remotos.

Licença

Apache-2.0