Grafana

Acesse e gerencie recursos do Grafana, incluindo dashboards, fontes de dados, Prometheus, Loki e alertas.

GitHubExperimente este MCPPatrocinado

Documentação

Forked de Grafana MCP server

Este repositório é um fork do servidor MCP original do Grafana.
Inclui modificações personalizadas listadas abaixo.

Alterações em relação ao upstream

  • Adicionado suporte para uma nova ferramenta: QuestDB
    • Introduzido o flag questdb para habilitar/desabilitar
    • Adicionado tools/questdb.go implementando a lógica de consulta do QuestDB
  • Adicionado suporte para uma nova ferramenta: Athena
    • Introduzido o flag athena para habilitar/desabilitar
    • Adicionado tools/athena.go implementando a lógica de consulta do Athena
  • Opções de transporte estendidas para suportar streamable-http
  • Adicionada dependência: github.com/DataDog/zstd

Servidor MCP do Grafana

Um servidor Model Context Protocol (MCP) para Grafana.

Isso fornece acesso à sua instância do Grafana e ao ecossistema ao redor.

Recursos

Os seguintes recursos estão atualmente disponíveis no servidor MCP. Esta lista é apenas para fins informativos e não representa um roadmap ou compromisso com recursos futuros.

Dashboards

  • Buscar dashboards: Encontre dashboards por título ou outros metadados
  • Obter dashboard por UID: Recupere detalhes completos do dashboard usando seu identificador único
  • Atualizar ou criar um dashboard: Modifique dashboards existentes ou crie novos. Nota: Use com cautela devido às limitações da janela de contexto; veja issue #101
  • Obter consultas de painéis e informações de datasource: Obtenha o título, a string de consulta e as informações do datasource (incluindo UID e tipo, se disponível) de cada painel em um dashboard

Datasources

  • Listar e buscar informações de datasource: Visualize todos os datasources configurados e recupere informações detalhadas sobre cada um.
    • Tipos de datasource suportados: Prometheus, Loki, QuestDB, Athena.

Consultas ao Prometheus

  • Consultar Prometheus: Execute consultas PromQL (suporta consultas de métricas instantâneas e de intervalo) contra datasources Prometheus.
  • Consultar metadados do Prometheus: Recupere metadados de métricas, nomes de métricas, nomes de labels e valores de labels de datasources Prometheus.

Consultas ao Loki

  • Consultar logs e métricas do Loki: Execute consultas de logs e consultas de métricas usando LogQL contra datasources Loki.
  • Consultar metadados do Loki: Recupere nomes de labels, valores de labels e estatísticas de streams de datasources Loki.

Incidentes

  • Buscar, criar, atualizar e encerrar incidentes: Gerencie incidentes no Grafana Incident, incluindo busca, criação, atualização e resolução de incidentes.

Investigações Sift

  • Criar investigações Sift: Inicie uma nova investigação Sift para analisar logs ou traces.
  • Listar investigações Sift: Recupere uma lista de investigações Sift, com suporte a um parâmetro de limite.
  • Obter investigação Sift: Recupere detalhes de uma investigação Sift específica pelo seu UUID.
  • Obter análises Sift: Recupere uma análise específica de uma investigação Sift.
  • Encontrar padrões de erro em logs: Detecte padrões elevados de erro em logs do Loki usando Sift.
  • Encontrar requisições lentas: Detecte requisições lentas usando Sift (Tempo).

Alertas

  • Listar e buscar informações de regras de alerta: Visualize regras de alerta e seus status (disparando/normal/erro/etc.) no Grafana.
  • Listar pontos de contato: Visualize pontos de contato de notificação configurados no Grafana.

Grafana OnCall

  • Listar e gerenciar escalas: Visualize e gerencie escalas de plantão no Grafana OnCall.
  • Obter detalhes de turnos: Recupere informações detalhadas sobre turnos de plantão específicos.
  • Obter usuários atuais de plantão: Veja quais usuários estão atualmente de plantão para uma escala.
  • Listar equipes e usuários: Visualize todas as equipes e usuários do OnCall.

Administração

  • Listar equipes: Visualize todas as equipes configuradas no Grafana.

A lista de ferramentas é configurável, então você pode escolher quais ferramentas deseja disponibilizar para o cliente MCP. Isso é útil se você não usa determinada funcionalidade ou se não quer ocupar muito da janela de contexto. Para desabilitar uma categoria de ferramentas, use o flag --disable-<category> ao iniciar o servidor. Por exemplo, para desabilitar as ferramentas do OnCall, use --disable-oncall.

Ferramentas

FerramentaCategoriaDescrição
list_teamsAdminListar todas as equipes
search_dashboardsBuscaBuscar dashboards
get_dashboard_by_uidDashboardObter um dashboard por uid
update_dashboardDashboardAtualizar ou criar um novo dashboard
get_dashboard_panel_queriesDashboardObter título do painel, consultas, UID e tipo do datasource de um dashboard
list_datasourcesDatasourcesListar datasources
get_datasource_by_uidDatasourcesObter um datasource por uid
get_datasource_by_nameDatasourcesObter um datasource por nome
query_prometheusPrometheusExecutar uma consulta contra um datasource Prometheus
list_prometheus_metric_metadataPrometheusListar metadados de métricas
list_prometheus_metric_namesPrometheusListar nomes de métricas disponíveis
list_prometheus_label_namesPrometheusListar nomes de labels que correspondem a um seletor
list_prometheus_label_valuesPrometheusListar valores para um label específico
list_incidentsIncidentListar incidentes no Grafana Incident
create_incidentIncidentCriar um incidente no Grafana Incident
add_activity_to_incidentIncidentAdicionar um item de atividade a um incidente no Grafana Incident
resolve_incidentIncidentResolver um incidente no Grafana Incident
query_loki_logsLokiConsultar e recuperar logs usando LogQL (consultas de log ou métricas)
list_loki_label_namesLokiListar todos os nomes de labels disponíveis nos logs
list_loki_label_valuesLokiListar valores para um label de log específico
query_loki_statsLokiObter estatísticas sobre streams de logs
list_alert_rulesAlertingListar regras de alerta
get_alert_rule_by_uidAlertingObter regra de alerta por UID
list_oncall_schedulesOnCallListar escalas do Grafana OnCall
get_oncall_shiftOnCallObter detalhes de um turno OnCall específico
get_current_oncall_usersOnCallObter usuários atualmente de plantão para uma escala específica
list_oncall_teamsOnCallListar equipes do Grafana OnCall
list_oncall_usersOnCallListar usuários do Grafana OnCall
get_investigationSiftRecuperar uma investigação Sift existente pelo seu UUID
get_analysisSiftRecuperar uma análise específica de uma investigação Sift
list_investigationsSiftRecuperar uma lista de investigações Sift com um limite opcional
find_error_pattern_logsSiftEncontra padrões elevados de erro em logs do Loki.
find_slow_requestsSiftEncontra requisições lentas dos datasources tempo relevantes.
list_pyroscope_label_namesPyroscopeListar nomes de labels que correspondem a um seletor
list_pyroscope_label_valuesPyroscopeListar valores de labels que correspondem a um seletor para um nome de label
list_pyroscope_profile_typesPyroscopeListar tipos de perfil disponíveis
fetch_pyroscope_profilePyroscopeBusca um perfil em formato DOT para análise
query_questdb_sqlQuestDBDatasource QuestDB: Executa SQL arbitrário e retorna os resultados como um array de objetos JSON, um por linha.
query_athena_sqlAthenaDatasource Athena: Executa SQL arbitrário e retorna os resultados como um array de objetos JSON, um por linha.

Uso

  1. Crie uma conta de serviço no Grafana com permissões suficientes para usar as ferramentas que deseja, gere um token de conta de serviço e copie-o para a área de transferência para uso no arquivo de configuração. Siga a documentação do Grafana para detalhes.

  2. Você tem várias opções para instalar mcp-grafana:

    • Imagem Docker: Use a imagem Docker pré-construída do Docker Hub.

      Importante: O entrypoint da imagem Docker está configurado para executar o servidor MCP em modo SSE por padrão, mas a maioria dos usuários vai querer usar o modo STDIO para integração direta com assistentes de IA como o Claude Desktop:

      1. Modo STDIO: Para o modo stdio, você deve substituir explicitamente o padrão com -t stdio e incluir o flag -i para manter o stdin aberto:
      docker pull mcp/grafana
docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<your service account token> mcp/grafana -t stdio
      1. Modo SSE: Neste modo, o servidor roda como um servidor HTTP ao qual os clientes se conectam. Você deve expor a porta 8000 usando o flag -p:
      docker pull mcp/grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<your service account token> mcp/grafana
      1. Modo HTTP Streamable: Neste modo, o servidor opera como um processo independente que pode lidar com múltiplas conexões de clientes. Você deve expor a porta 8000 usando o flag -p: Para este modo, você deve substituir explicitamente o padrão com -t streamable-http
      docker pull mcp/grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<your service account token> mcp/grafana -t streamable-http

    • Baixar binário: Baixe a versão mais recente de mcp-grafana na página de releases e coloque-a no seu $PATH.

    • Compilar a partir do código-fonte: Se você tiver um toolchain Go instalado, também pode compilar e instalar a partir do código-fonte, usando a variável de ambiente GOBIN para especificar o diretório onde o binário deve ser instalado. Isso também deve estar no seu PATH.

      GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

  3. Adicione a configuração do servidor ao seu arquivo de configuração do cliente. Por exemplo, para o Claude Desktop:

    Se estiver usando o binário:

    {
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

Nota: se você vir Error: spawn mcp-grafana ENOENT no Claude Desktop, você precisa especificar o caminho completo para mcp-grafana.

Se estiver usando Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_API_KEY",
        "mcp/grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

Nota: O argumento -t stdio é essencial aqui porque substitui o modo SSE padrão na imagem Docker.

Usando VSCode com servidor MCP remoto

Se você está usando VSCode e executando o servidor MCP em modo SSE (que é o padrão ao usar a imagem Docker sem substituir o transporte), certifique-se de que seu .vscode/settings.json inclua o seguinte:

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

Modo de Depuração

Você pode habilitar o modo de depuração para o transporte do Grafana adicionando o flag -debug ao comando. Isso fornecerá logs detalhados das requisições e respostas HTTP entre o servidor MCP e a API do Grafana, o que pode ser útil para solução de problemas.

Para usar o modo de depuração com a configuração do Claude Desktop, atualize sua configuração da seguinte forma:

Se estiver usando o binário:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["-debug"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

Se estiver usando Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_API_KEY",
        "mcp/grafana",
        "-t",
        "stdio",
        "-debug"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

Nota: Assim como na configuração padrão, o argumento -t stdio é necessário para substituir o modo SSE padrão na imagem Docker.

Desenvolvimento

Contribuições são bem-vindas! Por favor, abra uma issue ou envie um pull request se tiver sugestões ou melhorias.

Este projeto é escrito em Go. Instale o Go seguindo as instruções para sua plataforma. Para executar o servidor localmente no modo STDIO (que é o padrão para desenvolvimento local), use:

make run

Para executar o servidor localmente no modo SSE, use:

go run ./cmd/mcp-grafana --transport sse

Você também pode executar o servidor usando o transporte SSE dentro de uma imagem Docker personalizada. Assim como a imagem Docker publicada, o entrypoint desta imagem personalizada usa o modo SSE por padrão. Para construir a imagem, use:

make build-image

E para executar a imagem no modo SSE (o padrão), use:

docker run -it --rm -p 8000:8000 mcp-grafana:latest

Se você precisar executá-la no modo STDIO, substitua a configuração de transporte:

docker run -it --rm mcp-grafana:latest -t stdio

Testes

Existem três tipos de testes disponíveis:

  1. Testes Unitários (sem dependências externas necessárias):
make test-unit

Você também pode executar testes unitários com:

make test
  1. Testes de Integração (requer que os contêineres Docker estejam em execução):
make test-integration
  1. Testes de Nuvem (requer instância Grafana Cloud e credenciais):
make test-cloud

Nota: Os testes de nuvem são configurados automaticamente no CI. Para desenvolvimento local, você precisará configurar sua própria instância Grafana Cloud e credenciais.

Testes de integração mais abrangentes exigirão uma instância Grafana em execução localmente na porta 3000; você pode iniciar uma com Docker Compose:

docker-compose up -d

Os testes de integração podem ser executados com:

make test-all

Se você estiver adicionando mais ferramentas, adicione testes de integração para elas. Os testes existentes devem ser um bom ponto de partida.

Linting

Para fazer lint do código, execute:

make lint

Isso inclui um linter personalizado que verifica vírgulas não escapadas em tags de struct jsonschema. As vírgulas nos campos description devem ser escapadas com \\, para evitar truncamento silencioso. Você pode executar apenas este linter com:

make lint-jsonschema

Consulte a documentação do Linter JSONSchema para mais detalhes.

Licença

Este projeto está licenciado sob a Licença Apache, Versão 2.0.