Cloudflare MCP Server

@urdigital/mcp-server-cloudflare

Um servidor MCP (Model Context Protocol) que expõe a API GraphQL de Analytics da Cloudflare para Claude, Claude Code e qualquer outro cliente compatível com MCP — tráfego, largura de banda, ameaças e detalhamentos por país/código de status, para uma única zona da Cloudflare.

Instalação

Não é necessária instalação — execute diretamente com npx:

npx -y @urdigital/mcp-server-cloudflare

Configuração

Crie um token de API com escopo em dash.cloudflare.com → My Profile → API Tokens → Create Custom Token, com permissão Zone → Analytics → Read, com escopo para a zona específica (ou todas as zonas) da qual você deseja obter dados.

Você também precisa do Zone ID, encontrado na página de visão geral daquela zona no painel da Cloudflare (barra lateral direita).

Adicione à configuração do seu cliente MCP (por exemplo, o claude_desktop_config.json do Claude Desktop):

{
  "mcpServers": {
    "cloudflare": {
      "command": "npx",
      "args": ["-y", "@urdigital/mcp-server-cloudflare"],
      "env": {
        "CLOUDFLARE_API_TOKEN": "your-api-token",
        "CLOUDFLARE_ZONE_ID": "your-zone-id"
      }
    }
  }
}

Este servidor está atualmente limitado a uma zona por instância (associando um token a uma zona). Gerenciar várias zonas significa executar várias instâncias com diferentes variáveis de ambiente — a mesma compensação do design de um token por projeto do servidor Clarity.

Ferramentas

Ferramenta	Descrição
cloudflare_get_traffic_stats	Solicitações diárias, largura de banda, visualizações de página, visitantes únicos, ameaças
cloudflare_get_hourly_traffic_stats	Mesmas métricas, granularidade horária — limite de retenção de ~3 dias, veja abaixo
cloudflare_get_traffic_by_country	Visitas/largura de banda por país do cliente — limite de janela de consulta de 1 dia, veja abaixo
cloudflare_get_traffic_by_status_code	Visitas por código de status HTTP — limite de janela de consulta de 1 dia, veja abaixo
cloudflare_get_security_events	Eventos de firewall/WAF por ação, país, ASN — limitado por plano, pode não estar disponível, veja abaixo

Limites reais confirmados por testes em uma zona ativa

A API GraphQL de Analytics da Cloudflare expõe mais de 70 conjuntos de dados, e o acesso/limites de cada um variam conforme o nível do plano — estes não são hipotéticos; todos os três foram encontrados diretamente durante os testes:

• httpRequestsAdaptiveGroups (usado pelas ferramentas de detalhamento por país e código de status) rejeita qualquer janela de consulta maior que 1 dia em planos padrão, com um erro explícito: cannot request a time range wider than 1d, but your query time range spans 1w. Se você precisar de uma tendência mais longa, faça uma chamada por dia e agregue no lado do cliente — não solicite um intervalo amplo e espere que funcione.
• Dados com granularidade horária (httpRequests1hGroups) são retidos apenas por cerca de 3 dias e 1 hora a partir do momento atual. Solicitar dados horários mais antigos retorna: cannot request data older than 3d1h, but your query requests data from Xd.... Para qualquer período mais antigo, use granularidade diária (cloudflare_get_traffic_stats) em vez disso.
• firewallEventsAdaptiveGroups (eventos de segurança) não está disponível em todos os planos. Em uma zona do nível gratuito, isso retornou: zone '...' does not have access to the path. Esta é uma limitação documentada e conhecida da Cloudflare (confirmada pelos fóruns da comunidade deles, não específica deste servidor) — não é um bug, nem um problema de permissão de token. Se você encontrar isso, significa que o plano atual da zona não inclui esse conjunto de dados.

Comportamento específico do GraphQL que vale a pena conhecer

Diferentemente das APIs REST que os outros servidores neste monorepo utilizam, as APIs GraphQL (incluindo a da Cloudflare) podem retornar HTTP 200 com uma falha — o erro aparece em um array errors no corpo da resposta em vez do código de status HTTP. Este cliente verifica isso explicitamente em cada chamada; uma verificação simples de código de status trataria silenciosamente uma consulta com falha como sucesso.

Licença

MIT