loki
MCP server for querying Grafana Loki logs. Enables LLMs to execute LogQL queries, discover labels and their values, explore log series by se
Open source Open in the app JSON README (API)
About
MCP server for querying Grafana Loki logs. Enables LLMs to execute LogQL queries, discover labels and their values, explore log series by selectors, and retrieve index statistics — all via the Model Context Protocol. Supports basic auth, bearer token, and multi-tenant (X-Scope-OrgID) authentication.
Details
- Kind
- Plugins
- Topic
- Government & public data
- Publisher
- lexfrei
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 5
- Forks
- 3
- Open pull requests
- 3
- Last push
- 2026-08-30T23:41:37Z
- Repository state
- ativo
- Language
- Go
- License
- BSD-3-Clause
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
lexfrei/mcp-loki/loki
README
# MCP Loki
[](https://go.dev/)
[](LICENSE)
[](https://github.com/lexfrei/mcp-loki/releases)
[](https://github.com/lexfrei/mcp-loki/actions/workflows/release.yaml)
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:
```json
{
"mcpServers": {
"loki": {
"command": "podman",
"args": [
"run", "--rm", "-i",
"-e", "LOKI_URL=http://loki:3100",
"ghcr.io/lexfrei/mcp-loki:latest"
]
}
}
}
```
### Go Install
```bash
go install github.com/lexfrei/mcp-loki/cmd/mcp-loki@latest
```
MCP client configuration:
```json
{
"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):**
```json
{
"command": "podman",
"args": [
"run", "--rm", "-i",
"-e", "LOKI_URL=http://loki:3100",
"ghcr.io/lexfrei/mcp-loki:latest"
]
}
```
**Basic authentication:**
```json
{
"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):**
```json
{
"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:**
```text
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:**
```text
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:**
```text
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:**
```text
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:
```bash
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](LICENSE)