Loki MCP Server for AI Log Analysis

Overview

This MCP server bridges AI assistants with Grafana Loki so models can query, search, and reason over log data programmatically. Implemented as a Model Context Protocol (MCP) endpoint, the server accepts MCP requests (typically over stdio) from an assistant and translates them into Loki HTTP queries. The responses are structured for downstream reasoning: timestamps, labels, and contextual snippets are returned in a consistent format.

For developers, the server removes the friction of wiring assistant tooling to Loki. Rather than copying logs or crafting ad-hoc query adapters, you expose a small set of tools (query, search, label discovery) that the assistant can call directly. This enables smarter troubleshooting, automated incident summaries, and log-driven insights inside an LLM workflow.

Features

• Query LogQL (range and instant queries) against a Loki backend
• Keyword-based search with label filtering and boolean operators
• Stream label discovery and value enumeration
• MCP protocol compatibility for use with AI assistants (e.g., Claude, other MCP clients)
• Authentication: support for Basic Auth and Bearer tokens
• Configurable caching to reduce repeated Loki calls and improve latency
• Structured, enriched results including timestamps, labels, and surrounding context
• CLI entrypoint for local/dev usage; intended to be embedded in assistant MCP configurations

Installation / Configuration

Requirements:

• Python 3.8+
• Network access to a Grafana Loki instance

Install from source:

git clone https://github.com/mo-silent/loki-mcp-server.git
cd loki-mcp-server
pip install -e .

Development install (includes test and lint deps):

pip install -e ".[dev]"

Start the server (CLI):

loki-mcp-server

The server reads configuration from environment variables. Key variables:

Example .env:

LOKI_URL=http://localhost:3100
LOKI_BEARER_TOKEN=your-api-token

Production examples:

Basic auth

export LOKI_URL="https://loki.example.com"
export LOKI_USERNAME="service-account"
export LOKI_PASSWORD="secure-password"
loki-mcp-server

Bearer token

export LOKI_URL="https://loki.example.com"
export LOKI_BEARER_TOKEN="your-api-token"
loki-mcp-server

Available Tools

The MCP server exposes small, focused tools that an assistant can call.

• query_logs

  • Purpose: Run arbitrary LogQL queries (range or instant).
  • Parameters:
    • query (string, required)
    • start (RFC3339 or epoch ms, optional)
    • end (RFC3339 or epoch ms, optional)
    • limit (int, default 100)
    • direction (forward|backward)
  • Example:

    { "tool": "query_logs", "query": "{app=\"web\"} |= \"ERROR\"", "start": "2026-04-01T00:00:00Z", "end": "2026-04-01T01:00:00Z" }
    

• search_logs

  • Purpose: Keyword-driven search with label filters and boolean operators.
  • Parameters:
    • keywords (array[string], required)
    • labels (object, optional)
    • start, end, limit (optional)
    • case_sensitive (bool, default false)
    • operator (AND|OR, default AND)
  • Example:

    { "tool": "search_logs", "keywords": ["timeout","database"], "labels": {"environment":"prod"}, "limit": 50 }
    

• get_labels

  • Purpose: List available labels or values for a specific label within a time range.
  • Parameters:
    • label_name (string, optional)
    • start, end (optional)
    • use_cache (bool, default true)
  • Example:

    { "tool": "get_labels", "label_name": "job" }
    

Responses are returned as JSON with entries including timestamp, stream labels, and the log line or snippet. The server applies optional caching and will surface HTTP errors and rate-limit information where relevant.

Use Cases

• Incident Triage: An assistant can call search_logs to surface recent ERROR/exception patterns, group by label (pod, job, service), and produce a short root-cause hypothesis for on-call engineers.
• Alert Verification: Use query_logs to fetch logs for a specific alert window and validate whether the alert conditions correlate with application errors or infrastructure events.
• Trend Detection: Periodically run label discovery and top-N searches to detect spikes (e.g., increased 5xx responses) and feed those summaries into dashboards or incident reports.
• Log-driven Debugging: Combine fine-grained LogQL queries with surrounding context to let an assistant produce step-by-step debugging instructions based on exact traces in the logs.

Development & Troubleshooting

Run tests:

pytest

Run linters and formatters:

black .
isort .
ruff check .
mypy app/

Project layout (high level):

app/
├── main.py         # CLI entrypoint
├── server.py       # MCP server and message handling
├── config.py       # env/config parsing
├── loki_client.py  # HTTP client for Loki
├── query_builder.py# helpers for LogQL generation

Source and issues: https://github.com/mo-silent/loki-mcp-server

For integration, register the CLI as an MCP server in your assistant configuration so the model can call the three tools above. The server is intended to be small, auditable, and safe to run alongside assistant tooling in development and on-call environments.