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.

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:

LOKI_URL=http://loki:3100 MCP_HTTP_ADDR=:8080 loki-mcp-server
# MCP endpoint: http://localhost:8080/mcp

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

{
  "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 Support/Claude/claude_desktop_config.json on macOS):

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

Tools

query_range

Execute a LogQL range query against Loki to fetch logs over a time window.

query

Execute a LogQL instant query for point-in-time evaluation.

labels

List all available label names in Loki.

label_values

List values for a specific label.

series

Find active log stream series matching a selector.

Local Development Stack

A Docker Compose setup is included under deploy/ to spin up a full Loki environment for testing:

• Loki — log storage at http://localhost:3100
• Grafana — UI at http://localhost:3000 (anonymous admin, Loki pre-configured as datasource)
• Promtail — collects container logs and ships them to Loki
• Log generator — emits structured JSON logs with randomized apps (nginx, api, gateway, auth, payments), levels, and messages

# Start the stack
docker compose -f deploy/docker-compose.yml up -d

# Use loki-mcp-server against local Loki
LOKI_URL=http://localhost:3100 loki-mcp-server

# Stop the stack
docker compose -f deploy/docker-compose.yml down

Development

# Run tests
go test ./...

# Build
go build -o loki-mcp-server ./cmd/loki-mcp-server

# Vet
go vet ./...

⭐ If this project is useful for you, please star the repository.