Site-Shot

Servidor MCP oficial para a API de captura de tela do Site-Shot — capture_screenshot e capture_full_page com Chromium real, captura de página inteira, proxies por país e remoção de anúncios/banners de cookies.

GitHub

Documentação

Servidor MCP Site-Shot

Dê a Claude, Cursor e outros agentes de IA a capacidade de ver páginas web públicas — tire capturas de tela de sites com Site-Shot através do Model Context Protocol.

Renderização real com Chromium · captura de página inteira · proxies por país · remoção automática de anúncios e banners de cookies (imagens mais limpas, menos tokens de visão).

Uma chave de API do Site-Shot é necessária, e é preciso um plano pago da API do Site-Shot: as capturas consomem a cota e os limites de API já existentes dessa conta. A chave vem do seu dashboard do Site-Shot; preços lista os planos. A ferramenta de navegador sem cadastro em https://www.site-shot.com/ serve para verificar a qualidade da saída; ela não emite chaves.

Claude Code (plugin)

Este repositório também funciona como um marketplace de plugins do Claude Code. O plugin executa o pacote publicado site-shot-mcp via stdio e declara a chave de API como uma configuração sensível obrigatória, então o Claude Code pede a chave em vez de pedir que você a cole neste repositório, em um arquivo de configuração ou em uma mensagem de chat.

Instalação

claude plugin marketplace add site-shot/site-shot-mcp
claude plugin install site-shot@site-shot

ou de dentro de uma sessão:

/plugin marketplace add site-shot/site-shot-mcp
/plugin install site-shot@site-shot

Ambas as formas resolvem o marketplace pelo GitHub, então funcionam apenas depois que esses manifestos forem publicados no branch público padrão do repositório — não a partir de um branch local ou de um fork que você não tenha enviado.

Teste antes disso

Carregue o diretório do plugin para uma única sessão:

claude --plugin-dir /absolute/path/to/site-shot-mcp/plugins/site-shot

Duas coisas importam aqui. Passe um caminho absoluto — --plugin-dir é resolvido em relação ao diretório de trabalho da sessão. E inicie essa sessão a partir de um diretório de projeto comum, não deste checkout: este repositório é o pacote site-shot-mcp, então o npm resolve o nome localmente, não encontra um binário vinculado, e o servidor morre com sh: site-shot-mcp: command not found antes que o Claude Code o veja. De um diretório não relacionado, npx busca o pacote publicado e o inicia normalmente — verificado nos dois sentidos: saída 127 neste checkout, início stdio limpo em um vazio.

Para exercitar o caminho real de instalação — resolução de marketplace, manifestos e a configuração obrigatória — adicione o próprio checkout como um marketplace:

claude plugin marketplace add /absolute/path/to/site-shot-mcp
claude plugin install site-shot@site-shot

Isso instala no seu escopo de usuário; desfaça com claude plugin uninstall site-shot@site-shot e claude plugin marketplace remove site-shot.

A chave de API

O plugin declara SITESHOT_API_KEY como uma configuração obrigatória e sensível. O Claude Code pede a chave, a mascara enquanto você digita e a substitui no ambiente do servidor como ${user_config.SITESHOT_API_KEY}. O armazenamento do valor é responsabilidade do Claude Code.

Instalar sem uma não é um erro — o Claude Code registra como ainda pendente (1 userConfig option not yet set (1 required)). Forneça-a pelo prompt mascarado:

/plugin configure site-shot@site-shot

Configure-a antes de esperar uma captura: essa configuração é o que alimenta o servidor com a chave. O que o Claude Code faz enquanto ela não está definida — se o servidor é iniciado, se as ferramentas são oferecidas — é comportamento do próprio Claude Code e não é documentado aqui por observação.

O lado do servidor é independente disso. Quando executado diretamente via stdio sem uma chave, ele ainda inicia e imprime um aviso no stderr. As ferramentas de captura retornam um erro claro de chave ausente em vez de uma imagem.

O plugin adiciona uma habilidade (site-shot:website-screenshots) e as duas ferramentas de captura abaixo. Ele não declara hooks, monitores ou trabalhos de captura agendados; o único processo que ele inicia é o servidor MCP stdio declarado.

Codex CLI (plugin)

Este repositório também é um marketplace de plugins do Codex. Ele instala o mesmo diretório de plugin que o Claude Code — uma habilidade compartilhada, o mesmo site-shot-mcp@1.2.0 fixado via stdio — com seu próprio manifesto, porque os dois hosts conectam a credencial de forma diferente.

Instalação

codex plugin marketplace add site-shot/site-shot-mcp
codex plugin add site-shot@site-shot

Testado com Codex CLI 0.147.0 no macOS (arm64). Como no Claude Code, estes resolvem o marketplace pelo GitHub, então funcionam apenas quando esses manifestos estiverem no branch público padrão; antes disso, aponte codex plugin marketplace add para um caminho de checkout local.

Instalar não é o mesmo que estar configurado, e nenhum dos dois é o mesmo que uma captura bem-sucedida. A instalação apenas coloca os manifestos no lugar. O servidor ainda precisa da chave abaixo, e uma captura ainda precisa de um plano Site-Shot com cota restante.

A chave de API

O Codex encaminha a variável nomeada no descritor do plugin:

{ "command": "npx", "args": ["-y", "site-shot-mcp@1.2.0"], "env_vars": ["SITESHOT_API_KEY"] }

env_vars é uma lista de permissão de nomes, não de valores: nenhuma chave aparece neste descritor, no comando abaixo ou na entrada manual config.toml mais adiante. Você provisiona a chave no ambiente da sessão a partir da qual inicia o Codex.

O macOS usa zsh por padrão, onde read -p inicia um coprocesso em vez de imprimir um prompt — e um bloco de código rotulado como bash não muda o shell onde você cola. Invoque o bash explicitamente:

bash -c 'read -r -s -p "Site-Shot API key: " SITESHOT_API_KEY && printf "\n" && export SITESHOT_API_KEY && exec codex'

-s mantém a chave fora da tela, nada aqui a coloca em argv, e a exportação é limitada a essa sessão filha em vez de permanecer no shell de onde você digitou.

O que isso não faz é configurar um Codex que você inicia de outra forma. Um lançador de desktop ou uma sessão remota começa a partir do seu próprio ambiente, então executará o servidor sem uma chave até que você provisione uma lá também.

Configuração manual de MCP como alternativa

Se preferir não instalar o plugin, o mesmo servidor stdio pode ser configurado manualmente. Isso é uma alternativa ao plugin, não uma adição — execute ambos e você terá duas configurações de um único servidor. Escolha uma.

[mcp_servers.site-shot]
command = "npx"
args = ["-y", "site-shot-mcp@1.2.0"]
env_vars = ["SITESHOT_API_KEY"]

codex mcp add site-shot -- npx -y site-shot-mcp@1.2.0 escreve essa entrada para você; adicione env_vars depois, já que codex mcp add --env KEY=VALUE armazenaria a chave no arquivo em texto claro. Verifique com codex mcp get site-shot. Se você já tem uma entrada como esta e agora instala o plugin, remova a manual deliberadamente com codex mcp remove site-shot — nada aqui edita sua configuração por você.

Em qualquer caminho, a ressalva da seção do Claude Code se aplica: a menos que a entrada defina cwd, o Codex inicia o servidor de onde você executou o Codex, então executá-lo dentro deste repositório encontra a mesma colisão de nome local.

Claude Desktop e outros clientes MCP

Obtenha uma chave de API do Site-Shot em https://www.site-shot.com/start/.
Adicione isto à sua configuração do Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "site-shot": {
      "command": "npx",
      "args": ["-y", "site-shot-mcp"],
      "env": { "SITESHOT_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Reinicie o Claude Desktop. Peça para "tirar uma captura de tela de página inteira de https://news.ycombinator.com" e ele chamará o servidor e mostrará a imagem.

Funciona da mesma forma em qualquer cliente MCP (Cursor, Cline, VS Code, LangChain, CrewAI) — aponte o cliente para npx -y site-shot-mcp com SITESHOT_API_KEY no ambiente.

Cada integração acima executa o mesmo servidor stdio local, e esse pacote está publicado no npm e no Registro MCP oficial. Ele não está listado no diretório público compartilhado de plugins ChatGPT/Codex ou no diretório de conectores remotos do Claude: ambas as rotas exigem um endpoint MCP HTTPS hospedado, que o Site-Shot não implantou. Fazer isso é uma decisão separada.

Ferramentas

Duas ferramentas, ambas retornando a captura de tela como uma imagem MCP. Não há biblioteca salva, listagem, conversão para markdown ou agendamento — este servidor captura imagens e as devolve.

`capture_screenshot`

Capture a tela de uma página web (viewport por padrão).

Parâmetro	Tipo	Padrão	Observações
`url`	string (obrigatório)	—	Página a capturar
`full_page`	boolean	`false`	Capturar toda a página rolável
`width` / `height`	number	Padrão da API	Tamanho do viewport / dispositivo
`format`	`"png"` \| `"jpeg"` \| `"webp"`	`png`	Formato da imagem. `webp` é sem perdas, cerca de 35% menor que `png` na página mediana, máximo 16.383 px por lado
`block_ads`	boolean	`true`	Remover anúncios
`block_cookie_banners`	boolean	`true`	Remover pop-ups de consentimento de cookies
`country`	string	—	País do proxy como código de duas letras ISO 3166-1 alpha-2, ex.: `"DE"` (IP/idioma/fuso/geo automáticos)
`strict_country`	boolean	`true`	Errar se o país não tiver proxy, em vez de cair para os EUA
`language` / `time_zone` / `geolocation`	string	—	Substituições manuais
`wait_ms`	number	Padrão da API	Espera extra antes da captura (SPAs/animações)
`max_height`	number	20000 (página inteira)	Limite de altura capturada

Retorna a captura de tela como uma imagem MCP.

"Padrão da API" não é um número que este pacote possa declarar. width, height e wait_ms são encaminhados apenas quando você os passa, então o que se aplica quando você não os passa é decidido pela API do Site-Shot e pode mudar sem um lançamento aqui. Versões até 1.1.0 imprimiam tamanhos de pixel para width / height que a API não usa — um agente que os omitia para usar "o padrão" obtinha um viewport diferente, sem nada na imagem retornada para revelar isso. Passe valores explícitos sempre que o tamanho importar.

Códigos de país são códigos ISO, nunca nomes. Passe "DE", não "Germany". A API corresponde exatamente aos códigos e, caso contrário, renderizaria através de um proxy dos EUA sem avisar, então o servidor rejeita nomes completos antes de gastar uma renderização. strict_country (ativado por padrão) também transforma um país indisponível em erro em vez de uma captura silenciosa dos EUA — passe false para optar novamente pelo fallback. Países suportados →

`capture_full_page`

Igual a capture_screenshot com captura de página inteira habilitada.

Por que chamar este servidor em vez do navegador do próprio agente?

Se seu agente controla um navegador, ele pode capturar telas de páginas sozinho — e para páginas que exigem login ou passos em um fluxo, essa é a ferramenta certa. Para URLs públicas, delegar a captura a este servidor geralmente é uma engenharia melhor: cada captura executa o mesmo pipeline (sem replanejamento entre execuções), pode ser feita de um país específico com idioma e fuso horário correspondentes (country + strict_country), é avaliada por um classificador de imagens com uma escada de tentativas crescentes antes de ser retornada, e custa uma fração de centavo em vez de uma sessão de navegador mais tokens de visão por olhada. A comparação completa, com ambos os lados argumentados honestamente: Agente de IA vs. API de captura de tela — quem deve capturar a página.

Configuração

Variável de ambiente	Obrigatória	Descrição
`SITESHOT_API_KEY`	sim	Sua chave de API do Site-Shot (usada como `userkey`).

O servidor é um wrapper fino sobre a API HTTP existente do Site-Shot (https://api.site-shot.com/) — sem backend separado.

Desenvolvimento local

npm install
npm run check            # syntax check
npm run smoke            # offline tests (stubbed fetch, no API key needed)
node test/integration.mjs  # real stdio handshake against the local source
npm run test:plugin      # plugin/marketplace metadata tests
npm run validate:plugin  # claude plugin validate --strict (needs the claude CLI)
SITESHOT_API_KEY=yourkey npm start   # run the server on stdio

Requisitos

Node.js ≥ 18 (usa o fetch embutido).

Licença

MIT