loki-tail-mcp
An MCP server forGrafana Loki, designed around how LLMsactually query logs: compact output, hard row caps, and afuzzy container-name rescue that turns the classicempty-result-because-wrong-name failure into an auto-corrected retry oran actionable suggestion list. Built on thePython MCP SDK(FastMCP); runs as a local stdio server or a containerized StreamableHTTP service with bearer auth.
Tools
| Tool | Notes |
|---|---|
loki_tail_container |
"What is service X saying?" — the primary tool. Accepts approximate names: service vocabulary (vpn, proxy), bare names (sonarr), typos. On zero results it distinguishes valid-but-quiet from unknown name, auto-substitutes a unique fuzzy match (flagged in the output), or suggests candidates. |
loki_query_range |
Raw LogQL range query — multi-container correlation ({container=~"a|b"} |= "...") and metric queries (count_over_time(...)). |
loki_query_instant |
Instant query at a point in time (metric queries). |
loki_list_containers |
Durable container names (ephemeral CI/batch names hidden). |
loki_list_labels / loki_list_label_values |
Raw label discovery. |
loki_patterns |
Log pattern mining — thousands of lines → ranked recurring templates with counts. Requires the server-side pattern ingester (pattern_ingester.enabled: true). |
loki_log_volume |
Rank containers by log bytes over a window — "which service suddenly got noisy". |
loki_detected_fields |
Fields Loki can auto-extract from a stream (name/type/cardinality/parser) — discover | logfmt | status>=500 opportunities before writing LogQL. |
The name-resolution design
Matching always runs against live label values, never a hardcodedlist, so it survives renames. Resolution tries, in order: exact match →alias vocabulary → substring both ways → typo distance (difflib). Aunique candidate is tailed automatically and flagged; multiple candidatesbecome a ranked suggestion list. Auto-generated container names(docker/podman adjective_noun, hex-suffixed batch workers) are filteredout of discovery and suggestions but stay queryable via raw LogQL.
The built-in alias vocabulary covers the common self-hosted stack(vpn→gluetun, proxy→traefik, movies→radarr, …). Entries whosetargets don't exist in your fleet are inert; extend with your own viaLOKI_ALIASES.
Quick start (stdio)
// e.g. Claude Desktop claude_desktop_config.json / Claude Code .mcp.json
{
"mcpServers": {
"loki": {
"command": "uv",
"args": ["run", "--project", "/path/to/loki-tail-mcp", "loki-tail-mcp", "--stdio"],
"env": { "LOKI_URL": "http://your-loki-host:3100" }
}
}
}
stdio mode has no network surface and skips bearer auth — the client ownsthe process.
HTTP mode (container)
The bundled Containerfile builds a Streamable HTTP server at /mcp(stateless — restarts never strand client sessions). HTTP mode refusesto start without MCP_BEARER_TOKEN; clients authenticate withAuthorization: Bearer <token>.
podman build -t loki-tail-mcp . # or: docker build -t loki-tail-mcp .
podman run -d --name loki-tail-mcp -p 8325:8325 \
-e LOKI_URL=http://your-loki-host:3100 \
-e MCP_BEARER_TOKEN=some-long-random-token \
loki-tail-mcp
loki_tail_mcp.healthcheck does a full HTTP round-trip to /mcp (the 401counts as alive); wire it to your container healthcheck. Terminate TLS ata reverse proxy — the server itself speaks plain HTTP.
Configuration
| Env var | Default | Purpose |
|---|---|---|
LOKI_URL |
http://loki:3100 |
Loki base URL. |
LOKI_TENANT_ID |
(empty) | Sent as X-Scope-OrgID for multi-tenant Loki. |
LOKI_BASIC_AUTH |
(empty) | user:password for a basic-auth-fronted Loki (reverse proxy, Grafana Cloud). |
LOKI_TIMEOUT |
30 |
Upstream request timeout (s). |
LOKI_DEFAULT_LIMIT / LOKI_MAX_LIMIT |
100 / 1000 |
Row caps — Loki will happily return millions of rows; an MCP client will happily feed them to an LLM. Neither is what you want. |
LOKI_ALIASES |
(empty) | Extra vocabulary merged over the built-ins: term=fragment or term=frag|frag2, comma-separated (e.g. cache=redis|valkey,db=postgres). |
LOKI_EPHEMERAL_PATTERNS |
(built-ins) | Comma-separated regexes marking names as ephemeral; replaces the defaults when set. |
PORT |
8325 |
HTTP listen port. |
MCP_BEARER_TOKEN |
(empty) | Required in HTTP mode; server refuses to start without it. Not used in --stdio mode. |
Testing
# Full suite — mocked HTTP + pure resolution logic, no Loki needed
uv run --extra test pytest tests/ -v
License
MIT
