Grafana

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

GitHubExperimente este MCPPatrocinado

Documentação

Bifurcado de Servidor MCP do Grafana

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 roteiro 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 da fonte de dados: Obtenha o título, a string de consulta e as informações da fonte de dados (incluindo UID e tipo, se disponível) de cada painel em um dashboard

Fontes de dados

  • Listar e buscar informações de fontes de dados: Visualize todas as fontes de dados configuradas e recupere informações detalhadas sobre cada uma.
    • Tipos de fontes de dados suportados: Prometheus, Loki, QuestDB, Athena.

Consultas ao Prometheus

  • Consultar Prometheus: Execute consultas PromQL (suporta consultas de métricas instantâneas e de intervalo) contra fontes de dados Prometheus.
  • Consultar metadados do Prometheus: Recupere metadados de métricas, nomes de métricas, nomes de rótulos e valores de rótulos de fontes de dados Prometheus.

Consultas ao Loki

  • Consultar logs e métricas do Loki: Execute consultas de logs e consultas de métricas usando LogQL contra fontes de dados Loki.
  • Consultar metadados do Loki: Recupere nomes de rótulos, valores de rótulos e estatísticas de streams de fontes de dados 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, para que você possa escolher quais ferramentas deseja disponibilizar ao 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 da fonte de dados de um dashboard
list_datasourcesFontes de dadosListar fontes de dados
get_datasource_by_uidFontes de dadosObter uma fonte de dados por uid
get_datasource_by_nameFontes de dadosObter uma fonte de dados por nome
query_prometheusPrometheusExecutar uma consulta contra uma fonte de dados 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 rótulos que correspondem a um seletor
list_prometheus_label_valuesPrometheusListar valores para um rótulo específico
list_incidentsIncidenteListar incidentes no Grafana Incident
create_incidentIncidenteCriar um incidente no Grafana Incident
add_activity_to_incidentIncidenteAdicionar um item de atividade a um incidente no Grafana Incident
resolve_incidentIncidenteResolver 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 rótulos disponíveis em logs
list_loki_label_valuesLokiListar valores para um rótulo de log específico
query_loki_statsLokiObter estatísticas sobre streams de log
list_alert_rulesAlertasListar regras de alerta
get_alert_rule_by_uidAlertasObter regra de alerta por UID
list_oncall_schedulesOnCallListar escalas do Grafana OnCall
get_oncall_shiftOnCallObter detalhes de um turno específico do OnCall
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 nas fontes de dados tempo relevantes.
list_pyroscope_label_namesPyroscopeListar nomes de rótulos que correspondem a um seletor
list_pyroscope_label_valuesPyroscopeListar valores de rótulos que correspondem a um seletor para um nome de rótulo
list_pyroscope_profile_typesPyroscopeListar tipos de perfil disponíveis
fetch_pyroscope_profilePyroscopeBusca um perfil em formato DOT para análise
query_questdb_sqlQuestDBFonte de dados QuestDB: Executa SQL arbitrário e retorna os resultados como um array de objetos JSON, um por linha.
query_athena_sqlAthenaFonte de dados 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 executa 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á-lo no modo STDIO, substitua a configuração de transporte:

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

Testes

Há três tipos de testes disponíveis:

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

Você também pode executar os 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 na Nuvem (requer uma instância Grafana na nuvem e credenciais):
make test-cloud

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

Testes de integração mais abrangentes exigirão uma instância do Grafana em execução localmente na porta 3000; você pode iniciar uma com o 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 se há vírgulas não escapadas nas 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 Apache License, Versão 2.0.