MCP Loki

MCP server for querying Grafana Loki logs. Enables LLMs to search and analyze logs via 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
• Prompt Templates — Ready-made LogQL patterns for common log analysis tasks
• Multiple Auth Methods — Basic auth, Bearer token, multi-tenant (X-Scope-OrgID)
• Multi-arch Images — linux/amd64 and linux/arm64
• Signed Images — Verified with cosign keyless signing

Quick Start

Container (Podman/Docker)

Add 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"
      }
    }
  }
}

Configuration

All configuration is done via environment variables:

Variable	Required	Default	Description
LOKI_URL	No	http://localhost:3100	Loki server URL
LOKI_USERNAME	No	—	Basic auth username
LOKI_PASSWORD	No	—	Basic auth password
LOKI_TOKEN	No	—	Bearer token (alternative to basic auth)
LOKI_ORG_ID	No	—	X-Scope-OrgID header for multi-tenant Loki
MCP_HTTP_PORT	No	—	Enable HTTP SSE transport on this port

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"
  ]
}

Available Tools

loki_query

Execute LogQL queries against Loki.

Parameter	Type	Required	Description
query	string	Yes	LogQL query string
start	string	No	Start time (RFC3339, relative like 1h, or now)
end	string	No	End time (RFC3339, relative, or now)
limit	int	No	Maximum entries to return (default: 100)
direction	string	No	forward or backward (default: backward)

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.

Parameter	Type	Required	Description
name	string	No	Label name to get values for (omit for all labels)
start	string	No	Start time
end	string	No	End time

Example:

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

loki_series

Find log streams matching label selectors.

Parameter	Type	Required	Description
match	[]string	Yes	Label selector(s), e.g., {app="nginx"}
start	string	No	Start time
end	string	No	End time

Example:

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

loki_stats

Get index statistics for a query.

Parameter	Type	Required	Description
query	string	Yes	LogQL selector
start	string	No	Start time
end	string	No	End time

Example:

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

loki_ready

Check if Loki is ready to accept requests. No parameters required.

loki_config

Get Loki server configuration in YAML format. No parameters required.

Available Prompts

error_logs

Find error logs for a specific application.

Argument	Required	Default	Description
app	Yes	—	Application name to search errors for
timerange	No	1h	Time range (e.g. 1h, 30m, 7d)

rate_query

Calculate the rate of log lines matching a selector.

Argument	Required	Default	Description
selector	Yes	—	LogQL stream selector (e.g. {app="nginx"})
interval	No	5m	Rate interval (e.g. 5m, 1h)

top_label_values

Find top N values for a label by log volume.

Argument	Required	Default	Description
selector	Yes	—	LogQL stream selector (e.g. {app="nginx"})
label	Yes	—	Label name to group by
n	No	10	Number of top values to return
interval	No	5m	Rate interval (e.g. 5m, 1h)

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