loki-mcp-server

Loki MCP Server

     !Stars !MCP


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

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | query | string | yes | — | LogQL query expression | | start | string | no | 1 hour ago | Start of time range (RFC3339 or Unix nano) | | end | string | no | now | End of time range | | limit | number | no | 100 | Max entries (max 5000) | | direction | string | no | backward | forward or backward |

query

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

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | query | string | yes | — | LogQL query expression | | limit | number | no | 100 | Max entries (max 5000) | | time | string | no | now | Evaluation timestamp | | direction | string | no | backward | forward or backward |

labels

List all available label names in Loki.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | start | string | no | 6 hours ago | Start of time range | | end | string | no | now | End of time range |

label_values

List values for a specific label.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | label | string | yes | — | Label name | | start | string | no | 6 hours ago | Start of time range | | end | string | no | now | End of time range |

series

Find active log stream series matching a selector.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | match | string | yes | — | Stream selector (e.g. {app="nginx"}) | | start | string | no | 6 hours ago | Start of time range | | end | string | no | now | End of time range |

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.