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
- Multiple Auth Methods — Basic auth, Bearer token, multi-tenant (X-Scope-OrgID)
- Multi-arch Images —
linux/amd64andlinux/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"}
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