@mgcrea/mcp-loki

A Model Context Protocol server for the Grafana Loki HTTP API: query logs and LogQL metrics, explore labels, fields, volume and patterns, with answers shaped to fit a context window.

The server is read-only. It sends only reads: Loki's push, delete-request and ruler-write endpoints are not wrapped, and the loki_request escape hatch only sends GET.

Features

• Logs merged across streams, in time order. Labels every stream shares come once as common_labels. Each line keeps only the labels that tell its stream apart, plus level and structured metadata. Timestamps are exact RFC3339 nanoseconds, so the next cursor and loki_get_log_context anchors round-trip without loss.
• Cheap before expensive. loki_get_stats and loki_get_volume answer from the index without reading a line. loki_list_patterns summarizes what a service logs as templates. loki_query_metric counts and ranks without returning lines.
• Long lines are cut at max_line_chars (some services log 300 KB lines), ANSI colour codes are stripped, and the Kubernetes filename label is hidden by default.
• Errors carry a remedy. Loki answers a rejected query with plain text. The common ones (empty-compatible matchers, parse errors, range and series limits, timeouts) come back with what to change.
• Identity and limits up front. loki_auth_status names the tenant, the version, retention, max query length, max lines and series per query, and whether volume and patterns are enabled. Every data answer carries tenant.

Configure

| Variable | Required | Description | | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | LOKI_URL | yes | Loki base URL (gateway, query-frontend or single binary), with any path prefix. | | LOKI_USERNAME | no | Basic auth. Behind the Loki Helm chart's nginx gateway the username is the tenant. | | LOKI_PASSWORD | no | Basic auth password. | | LOKI_TOKEN | no | Bearer token instead of basic auth (Grafana Cloud, an OAuth proxy). | | LOKI_TENANT_ID | no | Sent as X-Scope-OrgID, for a multi-tenant Loki reached directly. A gateway that maps the basic-auth username overrides it. | | LOKI_HEADERS | no | Extra headers as a JSON object. | | LOKI_TIMEOUT | no | HTTP timeout per request, seconds (default 60). | | LOKI_MAX_RETRIES | no | Retries for 429 and proxy 502/503 (default 2). A 504 is never retried: on Loki it is a slow query, and a retry triples the load. |

With nothing configured the server still starts and serves loki_auth_status, which says what to set.

Quick start

pnpm install
pnpm build

Then copy .mcp.json.example to .mcp.json and fill it in.

Tools

| Tool | What it does | | --------------------------- | ---------------------------------------------------------------------------------- | | loki_auth_status | URL, auth, tenant, version and this tenant's limits; setup steps when unconfigured | | loki_query_logs | LogQL log query over a range, lines merged across streams, with a next cursor | | loki_get_log_context | The lines just before and after one line, in its own stream | | loki_query_metric | LogQL metric query at an instant, ranked largest first | | loki_query_metric_range | LogQL metric query over a range, on a step grid, with per-series stats | | loki_list_labels | Stream labels with their cardinality | | loki_list_label_values | Values of one label, optionally within a selector | | loki_list_series | Streams matching a selector | | loki_list_detected_fields | JSON / logfmt / structured-metadata fields in the lines, or one field's values | | loki_get_volume | Bytes per namespace / app / stream from the index, largest first | | loki_get_stats | Streams, chunks, lines and bytes a selector covers, from the index | | loki_list_patterns | Line templates with counts, from the pattern ingester | | loki_list_rules | The Loki ruler's alerting and recording rules | | loki_request | GET any other read endpoint (/loki/api/v1/*, /prometheus/api/v1/*, /config) |

Develop

pnpm dev            # tsdown --watch
pnpm test           # vitest
pnpm typecheck
pnpm lint
pnpm format

Publish

pnpm dlx release-it       # bump, commit, tag
git push --follow-tags    # CI publishes to npm from the tag

License

MIT