HUB
Sign inSign up

talkopsai/loki-mcp-server

By talkopsai

•Updated 3 days ago

MCP Server for Grafana Loki log exploration, LogQL queries, and schema discovery

Image
Developer tools
Monitoring & observability
0

517

talkopsai/loki-mcp-server repository overview

⁠Grafana Loki MCP Server

Let your AI assistant explore and analyze logs in Grafana Loki: discover labels and structured metadata, write bounded LogQL queries, summarize service errors, compare log patterns across releases, correlate trace IDs, and spot high-volume log streams.

⁠Quick Reference

⁠What You Get

  • 18 MCP tools (14 read-only) built for AI agents and MCP clients
  • 9 MCP resources under loki:// for structured context discovery
  • 6 Agent Skills bundled in /app/skills (browse on GitHub⁠)
  • Container ready: Runs as a minimal non-root image (linux/amd64, linux/arm64) with built-in query byte and time-window guardrails.
  • Safe by default: starts in read-only mode until you explicitly set MCP_ALLOW_WRITE=true.

⁠Quick Start (MCP Client over stdio)

Use this configuration in Claude Desktop, Cursor, Windsurf, or VS Code (mcp.json / claude_desktop_config.json):

{
  "mcpServers": {
    "loki": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "MCP_TRANSPORT=stdio",
        "-e",
        "LOKI_URL",
        "talkopsai/loki-mcp-server:latest"
      ],
      "env": {
        "LOKI_URL": "http://host.docker.internal:3100"
      }
    }
  }
}

Using Claude Code? Register it in one command:

claude mcp add loki -e LOKI_URL=http://host.docker.internal:3100 -- docker run -i --rm -e MCP_TRANSPORT=stdio -e LOKI_URL talkopsai/loki-mcp-server:latest

Restart your MCP client and try asking:

  • "What errors is the checkout service logging in the last 30 minutes?"
  • "Did the error rate go up after yesterday's release?"
  • "Find all logs for trace ID 4bf92f3577b34da6a3ce929d0e0e4736."

⁠Running Standalone (Streamable HTTP)

By default (MCP_TRANSPORT=http), the container starts an MCP Streamable HTTP server on port 8770 so multiple clients can share a single instance:

docker run --rm -p 8770:8770 \
  -e LOKI_URL=http://host.docker.internal:3100 \
  talkopsai/loki-mcp-server:latest

Point your MCP client at http://localhost:8770/mcp:

{
  "mcpServers": {
    "loki": {
      "url": "http://localhost:8770/mcp"
    }
  }
}

⁠Allowing Changes (Write Mode)

Out of the box, the container runs in read-only mode (MCP_ALLOW_WRITE=false). To allow mutations (updating Ruler rule groups, submitting log deletion requests, and applying Loki Operator CRDs), pass -e MCP_ALLOW_WRITE=true to docker run. Even with writes enabled, changes support dry-run previews and destructive operations require explicit confirmation.


⁠Environment Variables

VariableContainer DefaultDescription
LOKI_URLhttp://localhost:3100Loki base URL (use http://host.docker.internal:3100 for a host instance)
LOKI_ORG_IDnoneTenant ID (X-Scope-OrgID) for multi-tenant Loki
LOKI_AUTH_TOKENnoneBearer token for Loki authentication
MCP_ALLOW_WRITEfalseSet to true to enable rule mutations, log deletion, and Operator writes
MCP_TOOLSETSallFilter tools: discovery, query, analysis, diagnostics, rules, governance, operator, readonly
K8S_ENABLEDfalseSet to true (with mounted /app/.kube/config) for Loki Operator tools
MCP_TRANSPORThttphttp (standalone server) or stdio (MCP client subprocess)
MCP_PORT8770HTTP listen port inside the container

⁠Available Tools (18)

ToolAccessDescription
loki_analyze_volumeReadAttribute ingested log bytes and stream counts by label for FinOps optimization.
loki_apply_operator_crWriteValidate, preview (dry_run=True), or Server-Side Apply a Loki Operator CR.
loki_compare_periodsReadCompare log volume, error counts, and error signatures across two windows or versions.
loki_correlate_trace_logsReadFind and chronologically order all logs matching a trace_id or request_id.
loki_delete_rule_groupWrite (destructive)Preview (dry_run=True) or delete a Loki Ruler rule group after confirmation.
loki_get_detected_fieldsReadDiscover structured metadata, JSON keys, and logfmt fields with types and cardinalities in Loki 3.x streams.
loki_get_diagnosticsReadDiagnose Loki backend readiness, build version, and discarded log sample reasons.
loki_get_label_valuesReadRetrieve values for a specific indexed label in Grafana Loki, optionally scoped by stream selector.
loki_get_labelsReadList all indexed label names in Grafana Loki over an optional time window.
loki_get_log_patternsReadRetrieve recurring structural <_> log patterns and line counts from Loki's pattern ingester.
loki_get_query_statsReadEstimate streams, chunks, entries, and uncompressed bytes touched by a LogQL selector before execution.
loki_get_seriesReadReturn active Loki log stream label sets and per-label cardinality for a stream selector.
loki_manage_delete_requestsWrite (destructive)List, preview (dry_run=True), create, or cancel a Loki Compactor log deletion request.
loki_query_a2uiReadExecute a LogQL range query and flatten results into an interactive A2UI log table payload.
loki_query_instantReadEvaluate a LogQL metric or stream query at a single point in time.
loki_query_rangeReadExecute a LogQL range query returning log streams or metric time-series matrices with cost guardrails.
loki_summarize_service_logsReadCompute a high-signal service log health & error summary in one call.
loki_upsert_rule_groupWriteValidate, preview (dry_run=True), or upsert a Loki Ruler alerting/recording rule group.

⁠Bundled Agent Skills (6)

This image also ships step-by-step operational playbooks (SKILL.md) under /app/skills:

To copy the skills onto your workstation for Claude Code or Cursor:

docker run --rm --entrypoint tar talkopsai/loki-mcp-server:latest -C /app/skills -cf - . | tar -xf - -C ~/.claude/skills/

⁠Support & Community

Tag summary

Content type

Image

Digest

sha256:01850c31d…

Size

72 MB

Last updated

3 days ago

docker pull talkopsai/loki-mcp-server