talkopsai/loki-mcp-server repository overview

⁠Loki MCP Server by TalkOps.ai⁠

An MCP server that gives AI assistants the power to explore, query, and analyze logs from Grafana Loki — with LogQL query construction, log structure discovery, cardinality-aware schema exploration, and production-safe query guardrails.

⁠✨ Features

• Schema Discovery: Discover global label taxonomy, enumerate label values with scope queries, and validate active series with per-label cardinality — so the AI never halluccinates labels that don't exist.
• Log Structure Analysis: Detect structural log patterns via Loki's pattern ingester and discover JSON/logfmt keys with types, cardinality, and auto-suggested parser pipelines.
• Production-Safe Execution: Pre-check query cost (streams, chunks, bytes) against configurable guardrails, validate time windows, detect high-cardinality labels in selectors, and clamp result limits.
• Unified LogQL Execution: Both log range queries and metric queries (rate(), count_over_time(), avg_over_time()) handled by a single tool with automatic result formatting.
• Guided Workflows: Five built-in prompt workflows guide the AI through multi-step journeys — error investigation, health checks, log structure analysis, LogQL query building, and schema exploration.
• Multi-Tenancy: Bearer token, Basic Auth, and X-Scope-OrgID header injection for multi-tenant Loki deployments.

⁠🚀 How to Use This Image

This Docker image runs an MCP server that connects to your Grafana Loki backend. AI assistants (Claude, Cline, Cursor, or any MCP client) connect to the server over HTTP, SSE, or stdio.

⁠Running Standalone (HTTP Transport)

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

The server is now listening on http://localhost:8770/mcp.

Then configure your MCP client to connect:

{
  "mcpServers": {
    "loki": {
      "url": "http://localhost:8770/mcp",
      "description": "MCP Server for Grafana Loki log observability"
    }
  }
}

⁠Multi-Tenant Setup

For multi-tenant Loki deployments, inject the tenant org ID:

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

⁠🛠️ Configuration (Claude Desktop — Stdio)

To use this image over stdio transport directly inside Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

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

For authenticated or multi-tenant backends, add additional -e args:

{
  "mcpServers": {
    "loki-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "LOKI_URL=https://loki.example.com",
        "-e", "LOKI_AUTH_TOKEN=your-bearer-token",
        "-e", "LOKI_ORG_ID=my-tenant",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "MCP_LOG_LEVEL=INFO",
        "talkopsai/loki-mcp-server:latest"
      ]
    }
  }
}

⁠⚙️ Environment Variables

⁠Server Configuration

⁠Loki Backend

⁠Authentication

⁠Query Guardrails

⁠🔧 Available Tools (8 Total)

⁠Discovery

⁠Structure

⁠Safety

⁠Execution

⁠📖 Available Resources (8 URIs)

⁠🔐 Security Best Practices

1. Never expose the MCP server to the public internet without proper authentication.
2. All tools are read-only — the server only performs HTTP GET requests against Loki's query APIs. No data is created, modified, or deleted.
3. Tenant isolation: In multi-tenant deployments, verify that LOKI_ORG_ID is correctly scoped to prevent cross-tenant data leakage.
4. Protect auth credentials: LOKI_AUTH_TOKEN and LOKI_BASIC_AUTH_PASSWORD are included in every request to the backend — treat them as secrets.
5. Query guardrails: The server enforces byte, time window, limit, and cardinality thresholds. Review and tune for your environment.

⁠🐳 Docker Compose Example

services:
  loki-mcp-server:
    image: talkopsai/loki-mcp-server:latest
    ports:
      - "8770:8770"
    environment:
      - LOKI_URL=http://loki:3100
      - MCP_TRANSPORT=http
      - MCP_LOG_LEVEL=INFO
    depends_on:
      - loki

  loki:
    image: grafana/loki:latest
    ports:
      - "3100:3100"
    command: -config.file=/etc/loki/local-config.yaml

⁠🔗 Links and Resources

• Source Code: GitHub Repository⁠
• Full Documentation: README & Guides⁠
• Model Context Protocol: MCP Official Site⁠
• Grafana Loki: Loki Documentation⁠
• Report Issues: GitHub Issues⁠
• Discord: Join the Community⁠
• License: Apache 2.0⁠

If you find this MCP server useful, consider leaving a ⭐ on the GitHub repository⁠!