Skip to main content
Glama
snickery

loki-tail-mcp

by snickery
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

loki-tail-mcp

An MCP server for Grafana Loki, designed around how LLMs actually query logs: compact output, hard row caps, and a fuzzy container-name rescue that turns the classic empty-result-because-wrong-name failure into an auto-corrected retry or an actionable suggestion list. Built on the Python MCP SDK (FastMCP); runs as a local stdio server or a containerized Streamable HTTP 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 hardcoded list, so it survives renames. Resolution tries, in order: exact match → alias vocabulary → substring both ways → typo distance (difflib). A unique candidate is tailed automatically and flagged; multiple candidates become a ranked suggestion list. Auto-generated container names (docker/podman adjective_noun, hex-suffixed batch workers) are filtered out 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 whose targets don't exist in your fleet are inert; extend with your own via LOKI_ALIASES.

Related MCP server: Loki MCP Server

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 owns the process.

HTTP mode (container)

The bundled Containerfile builds a Streamable HTTP server at /mcp (stateless — restarts never strand client sessions). HTTP mode refuses to start without MCP_BEARER_TOKEN; clients authenticate with Authorization: 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 401 counts as alive); wire it to your container healthcheck. Terminate TLS at a 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

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • Overwatch MCP

    malindarathnayake
    A
    license
    -
    quality
    C
    maintenance
    An MCP server that enables querying logs and metrics from Graylog, Prometheus, and InfluxDB 2.x. It provides tools for executing Lucene log searches, PromQL queries, and Flux queries directly within MCP-compatible clients.
    Last updated
    MIT

  • grafana-mcp

    ninanung
    A
    license
    -
    quality
    D
    maintenance
    This MCP server enables natural-language querying of Grafana logs by automatically detecting log sources and service labels. It provides read-only access to log data with intelligent caching for efficient repeat queries.
    Last updated
    50
    MIT

View all related MCP servers

Related MCP Connectors

  • microservices.sh

    MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.

  • Darwin RAG

    Local-first RAG engine with MCP server for AI agent integration.

  • mcp-grafana

    An MCP server giving access to Grafana dashboards, data and more.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/snickery/loki-tail-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server