Servidor MCP Loki | Awesome MCP Servers

Loki MCP Server

Uma implementação de servidor em Go para o Model Context Protocol (MCP) com integração com Grafana Loki.

Começando

Pré-requisitos

Go 1.16 ou superior

Compilando e Executando

Compile e execute o servidor:

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

# Run the server
./loki-mcp-server

Ou execute diretamente com Go:

go run ./cmd/server

O servidor se comunica usando stdin/stdout seguindo o Model Context Protocol (MCP). Isso o torna adequado para uso com Claude Desktop e outros clientes compatíveis com MCP. Ele não executa como um servidor HTTP em uma porta.

Estrutura do Projeto

.
├── cmd/
│   ├── server/       # MCP server implementation
│   └── client/       # Client for testing the MCP server
├── internal/
│   ├── handlers/     # Tool handlers
│   └── models/       # Data models
├── pkg/
│   └── utils/        # Utility functions and shared code
└── go.mod            # Go module definition

Servidor MCP

O Loki MCP Server implementa o Model Context Protocol (MCP) e fornece as seguintes ferramentas:

Ferramenta de Consulta Loki

A ferramenta loki_query permite consultar dados de logs do Grafana Loki:

Parâmetros obrigatórios:
- query: String de consulta LogQL
Parâmetros opcionais:
- url: URL do servidor Loki (padrão: da variável de ambiente LOKI_URL ou http://localhost:3100)
- start: Hora de início da consulta (padrão: 1h atrás)
- end: Hora de término da consulta (padrão: agora)
- limit: Número máximo de entradas a retornar (padrão: 100)
- org: ID da organização para a consulta (enviado como cabeçalho X-Scope-OrgID)

Variáveis de Ambiente

A ferramenta de consulta Loki suporta as seguintes variáveis de ambiente:

LOKI_URL: URL padrão do servidor Loki a ser usada se não for especificada na solicitação
LOKI_ORG_ID: ID padrão da organização a ser usado se não for especificado na solicitação
LOKI_USERNAME: Nome de usuário padrão para autenticação básica se não for especificado na solicitação
LOKI_PASSWORD: Senha padrão para autenticação básica se não for especificada na solicitação
LOKI_TOKEN: Token de portador padrão para autenticação se não for especificado na solicitação

Nota de Segurança: Ao usar variáveis de ambiente de autenticação, tenha cuidado para não expor credenciais sensíveis em logs ou arquivos de configuração. Considere usar autenticação baseada em token em vez de nome de usuário/senha quando possível.

Testando o Servidor MCP

Você pode testar o servidor MCP usando o cliente fornecido:

# Build the client
go build -o loki-mcp-client ./cmd/client

# Loki query examples:
./loki-mcp-client loki_query "{job=\"varlogs\"}"
./loki-mcp-client loki_query "{job=\"varlogs\"}" "-1h" "now" 100

# Using environment variables:
export LOKI_URL="http://localhost:3100"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using environment variables for both URL and org:
export LOKI_URL="http://localhost:3100"
export LOKI_ORG_ID="tenant-123"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using environment variables for authentication:
export LOKI_URL="http://localhost:3100"
export LOKI_USERNAME="admin"
export LOKI_PASSWORD="password"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using environment variables with bearer token:
export LOKI_URL="http://localhost:3100"
export LOKI_TOKEN="your-bearer-token"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using all environment variables together:
export LOKI_URL="http://localhost:3100"
export LOKI_ORG_ID="tenant-123"
export LOKI_USERNAME="admin"
export LOKI_PASSWORD="password"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using org parameter for multi-tenant setups:
./loki-mcp-client loki_query "{job=\"varlogs\"}" "" "" "" "" "" "tenant-123"

Suporte a Docker

Você pode compilar e executar o servidor MCP usando Docker:

# Build the Docker image
docker build -t loki-mcp-server .

# Run the server
docker run --rm -i loki-mcp-server

Alternativamente, você pode usar Docker Compose:

# Build and run with Docker Compose
docker-compose up --build

Testes Locais com Loki

O projeto inclui uma configuração completa de Docker Compose para testar consultas Loki localmente:

Inicie o ambiente Docker Compose:
```
docker-compose up -d
```
Isso iniciará:
- Um servidor Loki na porta 3100
- Uma instância Grafana na porta 3000 (pré-configurada com Loki como fonte de dados)
- Um contêiner gerador de logs que envia logs de exemplo para o Loki
- O servidor Loki MCP

Use o script de teste fornecido para consultar logs:

# Run with default parameters (queries last 15 minutes of logs)
./test-loki-query.sh

# Query for error logs
./test-loki-query.sh '{job="varlogs"} |= "ERROR"'

# Specify a custom time range and limit
./test-loki-query.sh '{job="varlogs"}' '-1h' 'now' 50

Insira logs fictícios para teste:

# Insert 10 dummy logs with default settings
./insert-loki-logs.sh

# Insert 20 logs with custom job and app name
./insert-loki-logs.sh --num 20 --job "custom-job" --app "my-app"

# Insert logs with custom environment and interval
./insert-loki-logs.sh --env "production" --interval 0.5

# Show help message
./insert-loki-logs.sh --help

Acesse a interface Grafana em http://localhost:3000 para explorar logs visualmente.

Suporte a Server-Sent Events (SSE)

O servidor agora suporta dois modos de comunicação:

Entrada/saída padrão (stdin/stdout) seguindo o Model Context Protocol (MCP)
Servidor HTTP com endpoint Server-Sent Events (SSE) para integração com ferramentas como n8n

A porta padrão para o servidor HTTP é 8080, mas pode ser configurada usando a variável de ambiente SSE_PORT.

Endpoints do Servidor

Ao executar em modo HTTP, o servidor expõe os seguintes endpoints:

Endpoint SSE: http://localhost:8080/sse - Para streaming de eventos em tempo real
Endpoint MCP: http://localhost:8080/mcp - Para mensagens do protocolo MCP

Usando Docker com SSE

Ao executar o servidor com Docker, certifique-se de expor a porta 8080:

# Build the Docker image
docker build -t loki-mcp-server .

# Run the server with port mapping
docker run -p 8080:8080 --rm -i loki-mcp-server

Integração com n8n

Você pode integrar o Loki MCP Server com fluxos de trabalho n8n:

Instale o nó MCP Client Tools no n8n
Configure o nó com estes parâmetros:
- Endpoint SSE: http://your-server-address:8080/sse (substitua pelo endereço real do seu servidor)
- Autenticação: Escolha a autenticação apropriada, se necessário
- Ferramentas a Incluir: Escolha quais ferramentas Loki expor ao Agente de IA
Conecte o nó MCP Client Tool a um nó AI Agent que usará os recursos de consulta Loki

Exemplo de fluxo de trabalho: Trigger → MCP Client Tool (servidor Loki) → AI Agent (Claude)

Arquitetura

O Loki MCP Server usa uma arquitetura modular:

Servidor: A implementação principal do servidor MCP em cmd/server/main.go
Cliente: Um cliente de teste em cmd/client/main.go para interagir com o servidor MCP
Handlers: Handlers de ferramentas individuais em internal/handlers/
- loki.go: Funcionalidade de consulta Grafana Loki

Usando com Claude Desktop

Você pode usar este servidor MCP com Claude Desktop para adicionar ferramentas de consulta Loki. Siga estes passos:

Opção 1: Usando o Binário Compilado

Compile o servidor:

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

Adicione a configuração ao seu arquivo de configuração do Claude Desktop usando claude_desktop_config_binary.json.

Opção 2: Usando Go Run com um Script Shell

Torne o script executável:

chmod +x run-mcp-server.sh

Adicione a configuração ao seu arquivo de configuração do Claude Desktop usando claude_desktop_config_script.json.

Opção 3: Usando Docker (Recomendado)

Compile a imagem Docker:

docker build -t loki-mcp-server .

Adicione a configuração ao seu arquivo de configuração do Claude Desktop usando claude_desktop_config_docker.json.

Detalhes da Configuração

O arquivo de configuração do Claude Desktop está localizado em:

No macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
No Windows: %APPDATA%\Claude\claude_desktop_config.json
No Linux: ~/.config/Claude/claude_desktop_config.json

Você pode usar uma das configurações de exemplo fornecidas neste repositório:

claude_desktop_config.json: Modelo genérico
claude_desktop_config_example.json: Exemplo usando go run com o caminho atual
claude_desktop_config_binary.json: Exemplo usando o binário compilado
claude_desktop_config_script.json: Exemplo usando um script shell (recomendado para go run)
claude_desktop_config_docker.json: Exemplo usando Docker (mais confiável)

Notas:

Ao usar go run com Claude Desktop, você pode precisar definir várias variáveis de ambiente tanto no script quanto no arquivo de configuração:
- HOME: O diretório inicial do usuário
- GOPATH: O diretório do workspace Go
- GOMODCACHE: O diretório de cache de módulos Go
- GOCACHE: O diretório de cache de compilação Go
Essas são necessárias para garantir que o Go possa encontrar seus módulos e cache de compilação quando executado a partir do Claude Desktop.
Usar Docker é a abordagem mais confiável, pois empacota todas as dependências e variáveis de ambiente em um contêiner.

Ou crie sua própria configuração:

{
  "mcpServers": {
    "lokiserver": {
      "command": "path/to/loki-mcp-server",
      "args": [],
      "env": {
        "LOKI_URL": "http://localhost:3100",
        "LOKI_ORG_ID": "your-default-org-id",
        "LOKI_USERNAME": "your-username",
        "LOKI_PASSWORD": "your-password",
        "LOKI_TOKEN": "your-bearer-token"
      },
      "disabled": false,
      "autoApprove": ["loki_query"]
    }
  }
}

Certifique-se de substituir path/to/loki-mcp-server pelo caminho absoluto para o binário compilado ou código-fonte.

Reinicie o Claude Desktop.
Agora você pode usar as ferramentas no Claude:
- Exemplos de consulta Loki:
  - "Consulte Loki para logs com a consulta {job="varlogs"}"
  - "Encontre logs de erro da última hora no Loki usando a consulta {job="varlogs"} |= "ERROR""
  - "Mostre-me os 50 logs mais recentes do Loki com job=varlogs"
  - "Consulte Loki para logs com org 'tenant-123' usando a consulta {job="varlogs"}"

Usando ID de Organização em Prompts de Linguagem Natural

Ao usar este servidor MCP com Claude Desktop ou outros assistentes de IA, os usuários podem naturalmente mencionar o ID da organização em seus prompts de várias maneiras:

Referência Direta à Organização

"Consulte Loki para logs da organização 'tenant-123' com a consulta {job="varlogs"}"
"Pesquise logs Loki para org 'production-env' usando {job="web"}"
"Obtenha logs do ID de organização 'client-abc' correspondendo a {service="api"}"

Menções Contextuais à Organização

"Verifique os logs de erro do nosso tenant de produção (org: prod-001) usando a consulta {level="error"}"
"Encontre todos os logs da organização do cliente 'customer-xyz' da última hora"
"Consulte Loki com org tenant-456 para encontrar logs correspondentes a {job="backend"}"

Cenários Multi-tenant

"Mude para a organização 'dev-team' e consulte {job="logs"} para depuração"
"Use org 'staging-env' para pesquisar logs de aviso nas últimas 2 horas"
"Pesquise logs no tenant 'qa-environment' para quaisquer mensagens de erro"

Combinado com Outros Parâmetros

"Consulte Loki para a organização 'prod-cluster' de 2 horas atrás até agora com limite 50"
"Obtenha os últimos 100 logs da org 'microservice-team' para a consulta {app="payment"}"

Quando você menciona qualquer um desses prompts de linguagem natural, o assistente de IA mapeará automaticamente termos como "organização", "org", "tenant" ou "ID de organização" para o parâmetro org na ferramenta de consulta Loki, que é enviado como cabeçalho X-Scope-OrgID para o seu servidor Loki para filtragem multi-tenant adequada.

O segredo é mencionar naturalmente quaisquer parâmetros específicos na sua solicitação - a IA entenderá como mapeá-los para os parâmetros apropriados da ferramenta de consulta Loki. Quando os parâmetros não são explicitamente mencionados, o sistema usará automaticamente os padrões das variáveis de ambiente:

LOKI_URL para a URL do servidor Loki
LOKI_ORG_ID para o ID da organização
LOKI_USERNAME e LOKI_PASSWORD para autenticação básica
LOKI_TOKEN para autenticação com token de portador

Isso torna muito conveniente definir parâmetros de conexão padrão uma vez e depois usar consultas em linguagem natural sem precisar especificar detalhes de autenticação toda vez.

Usando com Cursor

Você também pode integrar o servidor Loki MCP com o editor Cursor. Para fazer isso, adicione a seguinte configuração às suas configurações do Cursor:

Configuração Docker:

{
  "mcpServers": {
    "loki-mcp-server": {
      "command": "docker",
      "args": ["run", "--rm", "-i", 
               "-e", "LOKI_URL=http://host.docker.internal:3100", 
               "-e", "LOKI_ORG_ID=your-default-org-id",
               "-e", "LOKI_USERNAME=your-username",
               "-e", "LOKI_PASSWORD=your-password",
               "-e", "LOKI_TOKEN=your-bearer-token",
               "loki-mcp-server:latest"]
    }
  }
}

Após adicionar esta configuração, reinicie o Cursor e você poderá usar a ferramenta de consulta Loki diretamente no editor.

Licença

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

Executando Testes

O projeto inclui testes unitários abrangentes e fluxos de trabalho CI/CD para garantir confiabilidade:

# Run all tests
go test ./...

# Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

# Run tests with race detection  
go test -race ./...

Correção de Bug de Timestamp (Issue #3)

Este projeto anteriormente tinha um bug crítico onde os timestamps eram exibidos como ano 2262 em vez de datas corretas. Isso foi corrigido e testes de regressão estão em vigor:

Causa Raiz: Loki retorna timestamps em nanossegundos, mas o código os tratava incorretamente como segundos e os multiplicava por 1.000.000.000
Correção: Tratar corretamente timestamps em nanossegundos do Loki
Testes: Testes abrangentes garantem que os timestamps sejam exibidos corretamente (ex.: 2024, 2023) em vez de 2262
Proteção CI: Testes automatizados previnem regressão deste bug crítico

Os testes verificam especificamente:

✅ Timestamps mostram anos corretos em vez de 2262
✅ Múltiplos formatos de timestamp funcionam corretamente
✅ Timestamps inválidos têm comportamento de fallback adequado
✅ Integração com instâncias Loki reais

Loki MCP Server

Documentação

Loki MCP Server

Começando

Pré-requisitos

Compilando e Executando

Estrutura do Projeto

Servidor MCP

Ferramenta de Consulta Loki

Variáveis de Ambiente

Testando o Servidor MCP

Suporte a Docker

Testes Locais com Loki

Suporte a Server-Sent Events (SSE)

Endpoints do Servidor

Usando Docker com SSE

Integração com n8n

Arquitetura

Usando com Claude Desktop

Opção 1: Usando o Binário Compilado

Opção 2: Usando Go Run com um Script Shell

Opção 3: Usando Docker (Recomendado)

Detalhes da Configuração

Usando ID de Organização em Prompts de Linguagem Natural

Referência Direta à Organização

Menções Contextuais à Organização

Cenários Multi-tenant

Combinado com Outros Parâmetros

Usando com Cursor

Licença

Executando Testes

Correção de Bug de Timestamp (Issue #3)