Grafana MCP — Instalar & Demo ao vivo

Name: Grafana MCP MCP Server
Author: grafana

Por que usar

Principais recursos

Query Prometheus / range query / labels / metadata
Query Loki LogQL + descoberta de labels
Busca de traces no Tempo
Lista/obtém dashboards; dados a nível de painel
Regras de alerta + instâncias de alerta + silêncios
Escalas e turnos OnCall
Investigações Sift (Grafana Cloud)
Modo somente-leitura suportado

Demo ao vivo

Como fica na prática

mcp-grafana.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-grafana": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_API_KEY",
        "mcp/grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "https://your-grafana.example.com",
        "GRAFANA_API_KEY": "${GRAFANA_API_KEY}"
      }
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-grafana": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_API_KEY",
        "mcp/grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "https://your-grafana.example.com",
        "GRAFANA_API_KEY": "${GRAFANA_API_KEY}"
      }
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-grafana": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_API_KEY",
        "mcp/grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "https://your-grafana.example.com",
        "GRAFANA_API_KEY": "${GRAFANA_API_KEY}"
      }
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-grafana": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_API_KEY",
        "mcp/grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "https://your-grafana.example.com",
        "GRAFANA_API_KEY": "${GRAFANA_API_KEY}"
      }
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-grafana",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_API_KEY",
        "mcp/grafana",
        "-t",
        "stdio"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-grafana": {
      "command": {
        "path": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "GRAFANA_URL",
          "-e",
          "GRAFANA_API_KEY",
          "mcp/grafana",
          "-t",
          "stdio"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add mcp-grafana -- docker run -i --rm -e GRAFANA_URL -e GRAFANA_API_KEY mcp/grafana -t stdio

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: Grafana MCP

Monte uma timeline de incidente a partir dos dados do Grafana

👤 SREs / plantão ⏱ ~10 min intermediate

Quando usar: O pager disparou; você quer uma timeline coerente antes de entrar na call.

Pré-requisitos

Token de service account do Grafana — Grafana → Administration → Service accounts; a role Editor é suficiente para consultas

Fluxo

O que está disparando

Grafana: liste alertas disparando nos últimos 30 minutos para service=checkout.✓ Copiado

→ list_alerts retorna 1+ alertas com timestamps
Busque a métrica

Para cada alerta, execute uma range query Prometheus para a métrica subjacente na última 1h. Observe o horário de violação.✓ Copiado

→ query_prometheus_range retorna série temporal
Busque logs no momento da violação

Loki: logs para service=checkout, level=error, [horário_violação-2m, horário_violação+2m]. Padrões principais.✓ Copiado

→ Linhas de log agrupadas por assinatura
Monte a timeline

Monte uma timeline concisa: alerta disparado → violação de métrica → top 3 padrões de log de erro. Markdown para Slack.✓ Copiado

→ Timeline pronta para colar

Resultado: Timeline de incidente coerente montada antes de você entrar na call.

Armadilhas

Query Loki muito ampla → estoura o budget de tokens — Sempre inclua label service=; limite a janela de tempo agressivamente
Query Prometheus com step muito fino — Use step=15s ou 30s para janelas de 1h

Combine com: sentry

Explique o que um dashboard Grafana realmente mostra

👤 Novo membro da equipe em onboarding ⏱ ~15 min beginner

Quando usar: Você herdou um dashboard e quer entendê-lo sem clicar em cada painel.

Fluxo

Encontre-o

Grafana: busque dashboards com o título 'Checkout SLO'.✓ Copiado

→ UID do dashboard retornado
Inspecione os painéis

Obtenha o dashboard. Para cada painel, resuma: título, datasource, qual query executa, qual threshold (se houver).✓ Copiado

→ Explicação por painel; strings de query incluídas

Resultado: Entendimento documentado do dashboard pronto para a wiki de onboarding.

Armadilhas

Variáveis substituídas de forma estranha — Mencione que a interpolação de $service/$env é em tempo de dashboard, não em tempo de MCP

Audite regras de alerta por ruído

👤 Líderes de SRE ⏱ ~30 min intermediate

Quando usar: Higiene trimestral — encontre regras que disparam constantemente ou nunca.

Fluxo

Busque as regras

Grafana: liste todas as regras de alerta na pasta Production.✓ Copiado

→ Lista de regras com UID + expressão
Obtenha histórico de disparos

Para cada uma, conte as instâncias de alerta nos últimos 30 dias. Sinalize regras com >100 (ruidosas) ou 0 (dormentes).✓ Copiado

→ Contagens por regra + conjunto sinalizado
Recomende

Para cada regra sinalizada, proponha uma correção: apertar o threshold, adicionar for: 5m ou deletar as dormentes.✓ Copiado

→ Alterações YAML concretas por regra

Resultado: Plano de limpeza concreto com YAML pronto para PR.

Armadilhas

Contar instâncias ≠ contar alertas únicos — Agrupe por labels; conte períodos distintos de disparo

Combine com: github

Combinações

Combine com outros MCPs para 10× de alavancagem

mcp-grafana + sentry

Correlacione erros do Sentry com violações de métricas/logs

Sentry: obtenha o pico de erros para OrderService. Grafana: busque Prometheus + Loki na mesma janela de tempo.✓ Copiado

mcp-grafana + github

Abra PR com limpezas de regras de alerta

Grafana: audite regras de alerta. GitHub: abra um PR substituindo as regras ruidosas por thresholds mais precisos.✓ Copiado

mcp-grafana + filesystem

Salve a timeline de incidente em um post-mortem Markdown

Monte a timeline a partir do Grafana, salve em /pm/2026-05-incident.md.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
list_datasources	(none)	Primeira chamada, descubra o que está disponível	1 API call
query_prometheus	datasource_uid, query, time?	Valor instantâneo de métrica	1 call
query_prometheus_range	datasource_uid, query, start, end, step	Investigação de série temporal	1 call
query_loki_logs	datasource_uid, expr, start, end, limit?	Buscar logs	1 call
search_dashboards	query: str	Encontrar um dashboard	1 call
get_dashboard	uid: str	Inspecionar painéis	1 call
list_alert_rules	folder?	Auditoria / descoberta	1 call
list_alert_instances	state?	O que está disparando agora	1 call
list_oncall_schedules	(none)	Quem está de plantão	1 call

Custo e limites

O que custa rodar

Cota de API: Limitado pelos limites da sua instância Grafana; Cloud tem caps de QPS por org
Tokens por chamada: 300–8000 (range queries podem ser grandes)
Monetário: OSS gratuito; Grafana Cloud cobra normalmente
Dica: Sempre passe step= em range queries; use Loki limit=100 a menos que você saiba o volume

Segurança

Permissões, segredos, alcance

Escopos mínimos: service-account with Viewer or Editor

Armazenamento de credenciais: Token de service account em variável de ambiente

Saída de dados: Apenas sua URL do Grafana

Nunca conceda: Admin role unless you need rule mutation

Use a flag --read-only se o Claude não deve conseguir mutar alertas/silêncios
Tokens de service account não expiram por padrão — rotacione trimestralmente

Solução de problemas

Erros comuns e correções

401 Unauthorized

Token errado ou service account desabilitado

Verificar: curl -H 'Authorization: Bearer $TOKEN' $URL/api/health

Prometheus query timeout

Reduza o intervalo de tempo ou o step

Loki 'parse error'

LogQL precisa de filtro de label à esquerda do pipeline; ex: {service="x"} |= "err"

Dashboard not found

UID mudou após importação; busque por título primeiro

Alternativas

Grafana MCP vs. outros

Alternativa	Quando usar	Troca
Direct Prometheus MCP	Apenas Prometheus, sem Grafana	Sem dashboards, sem integração com UI de alertas
Datadog MCP	Você usa Datadog	Stack de observabilidade diferente
Loki MCP standalone	Apenas logs	Superfície menor

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills