Grafana Loki

Servidor MCP Grafana-Loki

Um servidor FastMCP que permite consultar logs do Loki a partir do Grafana.

Configurações do Servidor MCP

{
  "mcpServers": {
    "loki": {
      "command": "uvx",
      "args": [
        "grafana-loki-mcp",
        "-u",
        "GRAFANA_URL",
        "-k",
        "GRAFANA_API_KEY"
      ]
    }
  }
}

• GRAFANA_URL: URL da sua instância do Grafana
• GRAFANA_API_KEY: Chave de API do Grafana com permissões apropriadas

Recursos

• Consultar logs do Loki através da API do Grafana
• Obter labels do Loki e valores de labels
• Formatar resultados de consulta em diferentes formatos (texto, JSON, markdown)
• Suporte para ambos os protocolos de transporte stdio e SSE

Requisitos

• Python 3.10+
• FastMCP
• Requests

Instalação

Usando pip

pip install grafana-loki-mcp

Configuração de Desenvolvimento

1. Clone este repositório
2. Instale as dependências usando uv:

# Install uv
pip install uv

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e ".[dev]"

Uso

Variáveis de Ambiente

Defina as seguintes variáveis de ambiente:

• GRAFANA_URL: URL da sua instância do Grafana
• GRAFANA_API_KEY: Chave de API do Grafana com permissões apropriadas

Argumentos de Linha de Comando

Você também pode fornecer esses valores como argumentos de linha de comando:

grafana-loki-mcp -u https://your-grafana-instance.com -k your-api-key

Opções adicionais:

• --transport: Protocolo de transporte a usar (stdio ou sse, padrão: stdio)

Executando o Servidor

# Using environment variables
export GRAFANA_URL=https://your-grafana-instance.com
export GRAFANA_API_KEY=your-api-key
grafana-loki-mcp

# Using command line arguments
grafana-loki-mcp -u https://your-grafana-instance.com -k your-api-key

# Using SSE transport
grafana-loki-mcp --transport sse

Desenvolvimento

Testes

Execute a suíte de testes:

pytest

Execute com cobertura:

pytest --cov=. --cov-report=term

Linting e Formatação

# Run ruff linter
ruff check .

# Run black formatter
black .

# Run type checking
mypy .

Ferramentas Disponíveis

query_loki

Consulta logs do Loki através do Grafana.

Parâmetros:

• query: string de consulta do Loki
• start: Tempo inicial (formato ISO, timestamp Unix ou tempo relativo estilo Grafana como 'now-1h', padrão: 1 hora atrás)
• end: Tempo final (formato ISO, timestamp Unix ou tempo relativo estilo Grafana como 'now', padrão: agora)
• limit: Número máximo de linhas de log a retornar (padrão: 100)
• direction: Direção da consulta ('forward' ou 'backward', padrão: 'backward')
• max_per_line: Máximo de caracteres por linha de log (0 para ilimitado, padrão: 100)

get_loki_labels

Obter todos os nomes de labels do Loki.

get_loki_label_values

Obter valores para um label específico do Loki.

Parâmetros:

• label: Nome do label

format_loki_results

Formata os resultados de consulta do Loki em um formato mais legível.

Parâmetros:

• results: Resultados da consulta do Loki de query_loki
• format_type: Formato de saída ('text', 'json' ou 'markdown', padrão: 'text')
• max_per_line: Máximo de caracteres por linha de log (0 para ilimitado, padrão: 0)

Exemplo de Uso

# Example client code
from mcp.client import Client

async with Client() as client:
    # Query Loki logs with max_per_line limit
    results = await client.call_tool(
        "query_loki",
        {
            "query": '{app="my-app"} |= "error"',
            "limit": 50,
            "max_per_line": 100,  # Limit log lines to 100 characters
            "start": "now-6h",    # Grafana-style relative time: 6 hours ago
            "end": "now"          # Current time
        }
    )

    # Format the results
    formatted = await client.call_tool(
        "format_loki_results",
        {
            "results": results,
            "format_type": "markdown",
            "max_per_line": 100  # Can also limit at formatting time
        }
    )

    print(formatted)

Licença

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