Simple Loki MCP Server

Consulte logs do Grafana Loki usando logcli com fallback automático para a API HTTP.

Documentação

Simple Loki MCP Server

O Loki MCP Server é uma interface Model Context Protocol (MCP) para consultar logs do Grafana Loki usando logcli. O servidor permite que assistentes de IA acessem e analisem dados de log do Loki diretamente.

Recursos

Consulte logs do Loki com suporte completo a LogQL
Obtenha valores de labels e metadados
Suporte a autenticação e configuração por meio de variáveis de ambiente ou arquivos de configuração
Fornece resultados formatados em diferentes formatos de saída (padrão, bruto, linhas JSON)
Fallback automático para a API HTTP quando logcli não estiver disponível no ambiente

Pré-requisitos

Node.js v16 ou superior
TypeScript
(Opcional) Grafana Loki logcli instalado e acessível no seu PATH. Se logcli não estiver disponível, o servidor usará automaticamente a API HTTP do Loki
Acesso a uma instância do servidor Loki

Instalação

Instalação via Smithery

Para instalar o Simple Loki MCP Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @ghrud92/simple-loki-mcp --client claude

para MCP

{
  "mcpServers": {
    "simple-loki": {
      "command": "npx",
      "args": ["-y", "simple-loki-mcp"],
      "env": {
        "LOKI_ADDR": "https://loki.sup.band"
      }
    }
  }
}

npm

Clone o repositório:

git clone https://github.com/ghrud92/loki-mcp.git
cd loki-mcp

Instale as dependências:

npm install

Compile o projeto:

npm run build

Ferramentas MCP Disponíveis

query-loki

Consulte logs do Loki com opções de filtragem.

Parâmetros:

query (obrigatório): string de consulta Loki (LogQL)
from: Timestamp de início (ex.: "2023-01-01T12:00:00Z")
to: Timestamp de fim (ex.: "2023-01-01T13:00:00Z")
limit: Número máximo de logs a retornar
batch: Tamanho do lote para resultados de consulta
output: Formato de saída ("default", "raw" ou "jsonl")
quiet: Suprimir metadados da consulta
forward: Exibir resultados em ordem cronológica

get-label-values

Recupere todos os valores de um label específico.

Parâmetros:

label (obrigatório): Nome do label para obter valores

get-labels

Recupere todos os labels disponíveis.

Nenhum parâmetro necessário.

Configuração

Você pode configurar o acesso ao Loki usando:

Variáveis de Ambiente

LOKI_ADDR: Endereço do servidor Loki (URL)
LOKI_USERNAME: Nome de usuário para autenticação básica
LOKI_PASSWORD: Senha para autenticação básica
LOKI_TENANT_ID: ID do tenant para Loki multi-tenant
LOKI_BEARER_TOKEN: Token Bearer para autenticação
LOKI_BEARER_TOKEN_FILE: Arquivo contendo o token Bearer
LOKI_CA_FILE: Arquivo CA personalizado para TLS
LOKI_CERT_FILE: Arquivo de certificado do cliente para TLS
LOKI_KEY_FILE: Arquivo de chave do cliente para TLS
LOKI_ORG_ID: ID da organização para configurações multi-org
LOKI_TLS_SKIP_VERIFY: Pular verificação TLS ("true" ou "false")
LOKI_CONFIG_PATH: Caminho personalizado para o arquivo de configuração
DEBUG: Ativar registro de depuração (debug logging)

Nota: Quando o cliente estiver usando o modo de API HTTP (quando logcli não estiver disponível), os mesmos parâmetros de configuração são usados para autenticar e conectar ao servidor Loki.

Arquivos de Configuração

Alternativamente, crie um arquivo logcli-config.yaml em um destes locais:

Caminho personalizado especificado por LOKI_CONFIG_PATH
Diretório de trabalho atual
Seu diretório pessoal (~/.logcli-config.yaml)

Exemplo de arquivo de configuração:

addr: https://loki.example.com
username: user
password: pass
tenant_id: mytenant

Uso

Inicie o servidor:

npm start

Para desenvolvimento:

npm run dev

Detalhes de Implementação

Fallback Automático para API HTTP

O servidor verificará automaticamente se logcli está instalado e disponível no ambiente:

Se logcli estiver disponível, ele será usado para todas as consultas, fornecendo a funcionalidade completa da ferramenta CLI
Se logcli não estiver disponível, o servidor fará fallback automaticamente para a API HTTP do Loki:
- Nenhuma configuração adicional é necessária
- Os mesmos parâmetros de autenticação são usados para a API HTTP
- A formatação das respostas é consistente com a saída do CLI
- O limite padrão de 1000 logs por consulta é aplicado em ambos os modos

Essa detecção automática garante que o servidor funcione perfeitamente em diferentes ambientes sem configuração manual.

Desenvolvimento

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Run tests
npm run test

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE.md para obter detalhes.