MCP Loki

🚀 MCP Loki

MCP Loki is an MCP server designed for querying Grafana Loki logs. It empowers LLMs to search and analyze logs through the Model Context Protocol.

✨ Features

• LogQL Queries: Execute range queries with flexible time ranges.
• Label Discovery: List labels and their values for query building.
• Series Exploration: Find log streams matching label selectors.
• Index Statistics: Get cardinality and size metrics.
• Multiple Auth Methods: Support basic auth, Bearer token, and multi-tenant (X-Scope-OrgID).
• Multi-arch Images: Available in linux/amd64 and linux/arm64 architectures.
• Signed Images: Verified with cosign keyless signing.

🚀 Quick Start

Container (Podman/Docker)

Add the following to your MCP client configuration:

{
  "mcpServers": {
    "loki": {
      "command": "podman",
      "args": [
        "run", "--rm", "-i",
        "-e", "LOKI_URL=http://loki:3100",
        "ghcr.io/lexfrei/mcp-loki:latest"
      ]
    }
  }
}

Go Install

go install github.com/lexfrei/mcp-loki/cmd/mcp-loki@latest

MCP client configuration:

{
  "mcpServers": {
    "loki": {
      "command": "mcp-loki",
      "env": {
        "LOKI_URL": "http://loki:3100"
      }
    }
  }
}

📦 Installation

All configuration is done via environment variables:

Authentication Examples

No authentication (local Loki):

{
  "command": "podman",
  "args": [
    "run", "--rm", "-i",
    "-e", "LOKI_URL=http://loki:3100",
    "ghcr.io/lexfrei/mcp-loki:latest"
  ]
}

Basic authentication:

{
  "command": "podman",
  "args": [
    "run", "--rm", "-i",
    "-e", "LOKI_URL=https://loki.example.com",
    "-e", "LOKI_USERNAME=admin",
    "-e", "LOKI_PASSWORD=secret",
    "ghcr.io/lexfrei/mcp-loki:latest"
  ]
}

Bearer token (Grafana Cloud):

{
  "command": "podman",
  "args": [
    "run", "--rm", "-i",
    "-e", "LOKI_URL=https://logs-prod-us-central1.grafana.net",
    "-e", "LOKI_TOKEN=glc_xxx",
    "-e", "LOKI_ORG_ID=123456",
    "ghcr.io/lexfrei/mcp-loki:latest"
  ]
}

💻 Usage Examples

loki_query

Execute LogQL queries against Loki.

Example:

Query the last hour of nginx error logs:
- query: {app="nginx"} |= "error"
- start: 1h
- limit: 50

loki_labels

Get label names or values for a specific label.

Example:

Get all label names: (no parameters)
Get values for "app" label: name=app

loki_series

Find log streams matching label selectors.

Example:

Find all nginx streams: match=["{app=\"nginx\"}"]

loki_stats

Get index statistics for a query.

Example:

Get stats for nginx logs: query={app="nginx"}

📚 Documentation

Time Formats

All time parameters accept:

• RFC3339: 2024-01-15T10:30:00Z
• Relative: 30s, 5m, 1h, 7d (seconds, minutes, hours, days ago)
• Keyword: now

Verification

Container images are signed with cosign keyless signing:

cosign verify ghcr.io/lexfrei/mcp-loki:latest \
  --certificate-identity-regexp=https://github.com/lexfrei/mcp-loki \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com

📄 License

BSD-3-Clause