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

brew install incu6us/tap/loki-mcp-server

Go install

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

Or build from source:

git clone https://github.com/incu6us/loki-mcp-server.git
cd loki-mcp
go build -o loki-mcp-server ./cmd/loki-mcp-server

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) |

Note: Basic auth (LOKI_USERNAME/LOKI_PASSWORD) and bearer token (LOKI_BEARER_TOKEN) are mutually exclusive.

Usage with Claude Code

Add to your Claude Code MCP configuration (~/.claude.json):

{
  "mcpServers": {
    "loki-mcp-server": {
      "type": "stdio",
      "command": "/path/to/loki-mcp-server",
      "args": [],
      "env": {
        "LOKI_URL": "http://loki:3100",
        "LOKI_USERNAME": "admin",
        "LOKI_PASSWORD": "secret"
      }
    }
  }
}

Usage with Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Suppor

... View full README on GitHub