incu6us/loki-mcp-server

Query Grafana Loki logs directly from AI agents using the Model Context Protocol (MCP).
Built in Go. Enables AI-powered log analysis using LogQL.
Supports integration with:
- Claude Desktop
- AI agent frameworks
- automation tools
- DevOps workflows
Motivation
The official grafana/loki-mcp exposes a single loki_query tool, which means the LLM must already know valid label names and values before it can build a query. This project takes a different approach by providing **5 granular tools** — labels, label_values, and series let the LLM discover what's available in Loki first, then construct precise query_range or query calls. The result is more accurate log retrieval with fewer wasted round-trips.
Additionally, this server enforces **strict input validation** (limit caps, direction validation, label name format checks, mutually exclusive auth) to surface errors early instead of forwarding bad requests to Loki.
Features
- **query_range** — Execute LogQL range queries to fetch logs over a time window
- **query** — Execute LogQL instant queries for point-in-time evaluation
- **labels** — List all available label names
- **label_values** — List values for a specific label
- **series** — Find active log stream series matching a selector
Installation
Homebrew
Go install
Or build from source:
Configuration
The server is configured entirely via environment variables, injected by the MCP client.
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| LOKI_URL | yes | — | Base URL of the Loki instance |
| LOKI_USERNAME | no | — | Basic auth username |
| LOKI_PASSWORD | no | — | Basic auth password |
| LOKI_BEARER_TOKEN | no | — | Bearer token authentication |
| LOKI_TLS_SKIP_VERIFY | no | false | Skip TLS certificate verification |
| LOKI_TENANT_ID | no | — | X-Scope-OrgID header for multi-tenant deployments |
| LOKI_HTTP_TIMEOUT | no | 30s | HTTP request timeout (Go duration, e.g. 10s, 1m) |
| MCP_HTTP_ADDR | no | — | Listen address for the streamable HTTP transport, e.g. :8080. Unset means stdio |
> **Note:** Basic auth (LOKI_USERNAME/LOKI_PASSWORD) and bearer token (LOKI_BEARER_TOKEN) are mutually exclusive.
Transports
By default the server speaks MCP over stdio, which is what Claude Code, Claude Desktop
and most local clients expect.
Set MCP_HTTP_ADDR to serve the streamable HTTP transport instead, for running the
server as a remote endpoint behind a proxy or gateway:
The HTTP mode is stateless, so it can run behind a load balancer with several replicas.
It carries no authentication of its own — put it behind TLS and an authenticating proxy
before exposing it, and remember that whoever reaches the endpoint can read every log
line the configured LOKI_URL credentials can see.
Usage with Claude Code
Add to your Claude Code MCP configuration (~/.claude.json):
Usage with Claude Desktop
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
Tools
query_range
Execute a LogQL range query against Loki to fetch logs over a time window.
| Parameter | Type | Required | Default | Description |