Loki MCP

Servidor Loki MCP

Consulte logs do Grafana Loki diretamente de agentes de IA usando o Model Context Protocol (MCP).

Construído em Go. Permite análise de logs com IA usando LogQL.

Suporta integração com:

• Claude Desktop
• Frameworks de agentes de IA
• Ferramentas de automação
• Fluxos de trabalho de DevOps

Motivação

O grafana/loki-mcp oficial expõe uma única ferramenta loki_query, o que significa que o LLM já precisa conhecer nomes e valores de labels válidos antes de conseguir montar uma consulta. Este projeto adota uma abordagem diferente ao fornecer 5 ferramentas granulares — labels, label_values e series permitem que o LLM descubra primeiro o que está disponível no Loki e depois construa chamadas precisas de query_range ou query. O resultado é uma recuperação de logs mais precisa, com menos idas e voltas desperdiçadas.

Além disso, este servidor aplica validação rigorosa de entrada (limites máximos, validação de direção, verificação de formato de nomes de labels, autenticação mutuamente exclusiva) para sinalizar erros cedo, em vez de encaminhar requisições inválidas ao Loki.

Recursos

• query_range — Executa consultas de intervalo LogQL para buscar logs em uma janela de tempo
• query — Executa consultas instantâneas LogQL para avaliação em um ponto no tempo
• labels — Lista todos os nomes de labels disponíveis
• label_values — Lista valores para um label específico
• series — Encontra séries de fluxos de log ativos que correspondem a um seletor

Instalação

Homebrew

brew install incu6us/tap/loki-mcp-server

Instalação via Go

go install github.com/incu6us/loki-mcp-server/cmd/loki-mcp-server@latest

Ou compile a partir do código-fonte:

git clone https://github.com/incu6us/loki-mcp-server.git
cd loki-mcp
go build -o loki-mcp-server ./cmd/loki-mcp-server

Configuração

O servidor é configurado inteiramente por variáveis de ambiente, injetadas pelo cliente MCP.

Variável	Obrigatória	Padrão	Descrição
LOKI_URL	sim	—	URL base da instância Loki
LOKI_USERNAME	não	—	Usuário de autenticação básica
LOKI_PASSWORD	não	—	Senha de autenticação básica
LOKI_BEARER_TOKEN	não	—	Autenticação por token Bearer
LOKI_TLS_SKIP_VERIFY	não	false	Ignorar verificação de certificado TLS
LOKI_TENANT_ID	não	—	Cabeçalho X-Scope-OrgID para implantações multi-tenant
LOKI_HTTP_TIMEOUT	não	30s	Tempo limite de requisição HTTP (duração Go, ex.: 10s, 1m)
MCP_HTTP_ADDR	não	—	Endereço de escuta para o transporte HTTP streamable, ex.: :8080. Não definido significa stdio

Nota: Autenticação básica (LOKI_USERNAME/LOKI_PASSWORD) e token Bearer (LOKI_BEARER_TOKEN) são mutuamente exclusivos.

Transportes

Por padrão, o servidor fala MCP via stdio, que é o que Claude Code, Claude Desktop e a maioria dos clientes locais esperam.

Defina MCP_HTTP_ADDR para servir o transporte HTTP streamable, para executar o servidor como um endpoint remoto atrás de um proxy ou gateway:

LOKI_URL=http://loki:3100 MCP_HTTP_ADDR=:8080 loki-mcp-server
# MCP endpoint: http://localhost:8080/mcp

O modo HTTP é stateless, portanto pode ser executado atrás de um balanceador de carga com várias réplicas. Ele não carrega autenticação própria — coloque-o atrás de TLS e de um proxy autenticador antes de expô-lo, e lembre-se de que qualquer pessoa que alcançar o endpoint pode ler todas as linhas de log que as credenciais LOKI_URL configuradas conseguem ver.

Uso com Claude Code

Adicione à sua configuração MCP do Claude Code (~/.claude.json):

{
  "mcpServers": {
    "loki-mcp-server": {
      "type": "stdio",
      "command": "/path/to/loki-mcp-server",
      "args": [],
      "env": {
        "LOKI_URL": "http://loki:3100",
        "LOKI_USERNAME": "admin",
        "LOKI_PASSWORD": "secret"
      }
    }
  }
}

Uso com Claude Desktop

Adicione à sua configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

{
  "mcpServers": {
    "loki-mcp-server": {
      "type": "stdio",
      "command": "/path/to/loki-mcp-server",
      "args": [],
      "env": {
        "LOKI_URL": "http://loki:3100",
        "LOKI_USERNAME": "admin",
        "LOKI_PASSWORD": "secret"
      }
    }
  }
}

Ferramentas

query_range

Executa uma consulta de intervalo LogQL contra o Loki para buscar logs em uma janela de tempo.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
query	string	sim	—	Expressão de consulta LogQL
start	string	não	1 hora atrás	Início do intervalo de tempo (RFC3339 ou Unix nano)
end	string	não	agora	Fim do intervalo de tempo
limit	number	não	100	Máximo de entradas (máx. 5000)
direction	string	não	backward	forward ou backward

query

Executa uma consulta instantânea LogQL para avaliação em um ponto no tempo.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
query	string	sim	—	Expressão de consulta LogQL
limit	number	não	100	Máximo de entradas (máx. 5000)
time	string	não	agora	Carimbo de tempo da avaliação
direction	string	não	backward	forward ou backward

labels

Lista todos os nomes de labels disponíveis no Loki.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
start	string	não	6 horas atrás	Início do intervalo de tempo
end	string	não	agora	Fim do intervalo de tempo

label_values

Lista valores para um label específico.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
label	string	sim	—	Nome do label
start	string	não	6 horas atrás	Início do intervalo de tempo
end	string	não	agora	Fim do intervalo de tempo

series

Encontra séries de fluxos de log ativos que correspondem a um seletor.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
match	string	sim	—	Seletor de fluxo (ex.: {app="nginx"})
start	string	não	6 horas atrás	Início do intervalo de tempo
end	string	não	agora	Fim do intervalo de tempo

Stack de Desenvolvimento Local

Uma configuração Docker Compose está incluída em deploy/ para subir um ambiente Loki completo para testes:

• Loki — armazenamento de logs em http://localhost:3100
• Grafana — interface em http://localhost:3000 (admin anônimo, Loki pré-configurado como fonte de dados)
• Promtail — coleta logs de contêineres e os envia para o Loki
• Gerador de logs — emite logs JSON estruturados com aplicativos aleatórios (nginx, api, gateway, auth, payments), níveis e mensagens

# Start the stack
docker compose -f deploy/docker-compose.yml up -d

# Use loki-mcp-server against local Loki
LOKI_URL=http://localhost:3100 loki-mcp-server

# Stop the stack
docker compose -f deploy/docker-compose.yml down

Desenvolvimento

# Run tests
go test ./...

# Build
go build -o loki-mcp-server ./cmd/loki-mcp-server

# Vet
go vet ./...

⭐ Se este projeto for útil para você, por favor dê uma estrela no repositório.