Apresentação Detalhada do Projeto Grafana MCP Server

Visão Geral do Projeto

O Grafana MCP Server é um servidor baseado no Protocolo de Contexto de Modelo (Model Context Protocol, MCP), projetado especificamente para integração com instâncias do Grafana e seu ecossistema circundante. Este projeto oferece a agentes de IA (como o Claude Desktop) a capacidade de acessar e manipular várias funcionalidades do Grafana.

Principais Características e Funcionalidades

Gerenciamento de Painéis

• Pesquisar Painéis: Recuperar e localizar rapidamente painéis específicos.
• Obter Painel: Obter a configuração completa do painel através do UID.
• Atualizar/Criar Painel: Modificar dinamicamente ou criar novos painéis (atenção às limitações da janela de contexto).

Integração de Fontes de Dados

• Gerenciamento de Fontes de Dados: Listar e obter informações sobre as fontes de dados.
• Suporte a Consultas de Múltiplas Fontes de Dados:
  • Prometheus: Executar consultas PromQL para obter dados de métricas.
  • Loki: Executar consultas LogQL para recuperar dados de logs.
  • Tempo: Consulta de dados de rastreamento distribuído.
  • Pyroscope: Consulta de dados de análise de desempenho.

Consulta de Metadados

• Metadados do Prometheus: Obter metadados de métricas, nomes de métricas, nomes de rótulos e valores de rótulos.
• Metadados do Loki: Obter nomes de rótulos de logs, valores de rótulos e informações estatísticas.

Gerenciamento de Eventos e Alertas

• Gerenciamento de Eventos: Pesquisar, criar, atualizar e fechar eventos.
• Regras de Alerta: Listar e obter informações sobre regras de alerta, obter o status dos alertas.
• Gerenciamento de Pontos de Contato: Listar, criar e modificar pontos de contato de alerta.

Integração com Grafana OnCall

• Gerenciamento de Escalonamento: Listar e gerenciar planos de plantão.
• Informações de Plantão: Obter detalhes do plantão e o usuário atual em plantão.
• Gerenciamento de Equipes e Usuários: Gerenciar equipes e informações de usuários.
• Gerenciamento de Grupos de Alerta: Listar grupos de alerta.

Funcionalidade de Investigação Sift

• Investigação Inteligente: Iniciar investigações Sift e visualizar os resultados.
• Gerenciamento de Investigações: Criar, listar e obter informações sobre investigações.
• Funcionalidades de Análise: Obter resultados de análise de investigações.
• Reconhecimento de Padrões de Erro: Encontrar padrões de erro em logs.
• Análise de Desempenho: Identificar solicitações lentas.

Configuração de Ferramentas

Este projeto oferece opções flexíveis de configuração de ferramentas, permitindo que você habilite ou desabilite categorias de funcionalidades específicas:

Nome da Ferramenta	Categoria	Descrição
search_dashboards	Search	Pesquisar painéis
get_dashboard_by_uid	Dashboard	Obter painel por UID
update_dashboard	Dashboard	Atualizar ou criar novo painel
list_datasources	Datasources	Listar fontes de dados
query_prometheus	Prometheus	Executar consulta Prometheus
query_loki_logs	Loki	Consultar e recuperar logs
list_incidents	Incident	Listar eventos
list_alert_rules	Alerting	Listar regras de alerta
list_oncall_schedules	OnCall	Listar planos de plantão OnCall
find_error_pattern_logs	Sift	Encontrar padrões de erro

Use a flag --disable-<categoria> para desabilitar categorias de ferramentas específicas. Por exemplo, use --disable-oncall para desabilitar ferramentas relacionadas ao OnCall.

Instalação e Configuração

Métodos de Instalação

1. Imagem Docker

docker pull mcp/grafana
docker run -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<your_token> mcp/grafana

2. Download do Arquivo Binário

Baixe a versão mais recente da página de releases e coloque-a no diretório $PATH.

3. Compilação do Código Fonte

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

Configurações

Pré-requisitos

1. Crie uma conta de serviço no Grafana e atribua permissões suficientes.
2. Gere um token de conta de serviço.

Configuração do Claude Desktop

Usando o arquivo binário:

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

Usando Docker:

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

Modo de Depuração

Habilite o modo de depuração adicionando a flag -debug para fornecer logs detalhados de solicitações e respostas HTTP:

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

Desenvolvimento e Testes

Configuração do Ambiente de Desenvolvimento

# Executar o servidor
make run

# Construir a imagem Docker
make build-image

# Executar o contêiner Docker
docker run -it --rm -p 8000:8000 mcp-grafana:latest

Tipos de Testes

Testes Unitários

make test-unit
# Ou
make test

Testes de Integração

# Requer a inicialização do contêiner Docker
make test-integration

Testes na Nuvem

# Requer uma instância do Grafana na nuvem e credenciais
make test-cloud

Testes Completos

# Iniciar uma instância local do Grafana
docker-compose up -d

# Executar todos os testes
make test-all

Qualidade do Código

Verificação de Código

make lint

Verificação do Schema JSON

Este projeto inclui um linter personalizado para verificar vírgulas não escapadas nas tags de estrutura jsonschema:

make lint-jsonschema

Arquitetura Técnica

• Linguagem de Programação: Go
• Protocolo: Model Context Protocol (MCP)
• Método de Comunicação: stdin/stdout ou SSE (Server-Sent Events)
• Clientes Suportados: Claude Desktop e outros clientes compatíveis com MCP

Casos de Uso

1. Monitoramento Impulsionado por IA: Permitir que agentes de IA consultem e analisem dados de monitoramento de forma inteligente.
2. Automação de Operações: Criar e gerenciar automaticamente painéis e regras de alerta através de IA.
3. Resposta Inteligente a Incidentes: Utilizar IA para analisar logs e métricas, localizando e resolvendo problemas rapidamente.
4. Insights de Dados: Permitir que a IA ajude a extrair informações valiosas de dados de monitoramento complexos.

Este projeto representa uma nova tendência na integração de IA com ferramentas de monitoramento tradicionais, fornecendo aos desenvolvedores uma ponte poderosa que conecta assistentes de inteligência artificial e o ecossistema Grafana.