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.

Related MCP server: Overwatch MCP

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.