Loki MCP Server

An MCP server that gives AI assistants the power to explore, query, and analyze logs from Grafana Loki — with LogQL query construction, log structure discovery, cardinality-aware schema exploration, and production-safe query guardrails.

Quick Start · Docs · Report Bug · Request Feature

Why Loki MCP Server?

The problem: Grafana Loki is the industry-standard log aggregation system, but effective log analysis is complex. Writing LogQL queries requires knowledge of stream selectors, line filters, parser stages, and metric functions. Understanding the label taxonomy, avoiding high-cardinality pitfalls, and building efficient parser pipelines each require specialized knowledge. When AI assistants try to help, they hallucinate label names, guess at field structures, construct unbounded queries that overwhelm backends, or miss the discovery-first workflow that experienced SREs follow.

The solution: The Loki MCP Server gives AI assistants (like Claude, Cline, or Cursor) structured, safe tools to interact with Grafana Loki natively:

1. Schema Discovery: Say "What labels exist in my Loki cluster?" and the AI discovers all label names, their values, and active series counts — so it never hallucates labels that don't exist.
2. Log Structure Analysis: Say "What fields can I query in checkout-service logs?" and the AI discovers JSON/logfmt keys, their types, estimated cardinality, and the parser needed to extract them — all before writing a single LogQL pipeline.
3. Production-Safe Execution: The AI pre-checks query cost (streams, chunks, bytes) against configurable guardrails, validates time windows, detects high-cardinality labels in selectors, and clamps result limits — protecting both the AI's context window and the Loki backend.
4. Unified Query Execution: Both log range queries and metric queries (rate(), count_over_time(), avg_over_time()) are handled by a single tool with automatic result formatting.
5. Guided Workflows: Five built-in prompt workflows guide the AI through multi-step journeys — error investigation, health checks, log structure analysis, LogQL query building, and schema exploration.

Key Features

Label & Schema Discovery

• Global label taxonomy discovery (get_cluster_labels)
• Label value enumeration with optional scope queries (get_label_values)
• Active series validation with per-label cardinality and high-cardinality warnings (get_active_series)

Log Structure Analysis

• Structural pattern detection via Loki's pattern ingester (get_log_patterns)
• Detected field discovery — JSON/logfmt keys, types, cardinality, and parser hints (get_detected_fields)
• Auto-suggested parser pipelines (| pattern "<pattern>")

Production-Safe Query Execution

• Preflight cost estimation: streams, chunks, entries, bytes with human-readable output (get_query_stats)
• Configurable guardrails: max query bytes (5 GB default), max time window (14 days), max log limit (5000), high-cardinality threshold (10,000)
• Automatic cost-based query rejection when byte threshold is exceeded
• High-cardinality label detection in stream selectors with inline warnings

Unified LogQL Execution

• Instant queries for point-in-time scalar answers (execute_logql_instant)
• Range queries for log streams and metric time-series (execute_logql_query)
• Interactive dynamic UI rendering for A2UI log tables (loki_query_a2ui)
• Support for rate(), count_over_time(), avg_over_time(), sum_over_time(), quantile_over_time(), histogram_over_time()
• Configurable step size for metric queries

Multi-Tenancy

• Bearer token and Basic Auth support
• X-Scope-OrgID header injection for multi-tenant Loki deployments
• Configurable via environment variables

Production-Ready Infrastructure

• Structured JSON logging with configurable log levels
• Frozen dataclass configuration (immutable at runtime)
• Middleware stack: error handling, response limiting, rate limiting, structured logging, timing

Architecture

                    ┌─────────────────────────┐
                    │     MCP Client          │
                    │ (Claude, Cline, Cursor) │
                    └──────────┬──────────────┘
                               │
                    ┌──────────▼──────────────┐
                    │   FastMCP Server Core   │
                    │  (HTTP / SSE / stdio)   │
                    │  + Middleware Stack      │
                    └──────────┬──────────────┘
                               │
       ┌────────────┬──────────┼──────────┬────────────┐
       │            │          │          │            │
  ┌────▼────┐ ┌────▼────┐ ┌───▼───┐ ┌────▼────┐ ┌────▼────┐
  │  Tools  │ │Resources│ │Prompts│ │  Utils  │ │ Models  │
  │   (8)   │ │   (8)   │ │  (5)  │ │         │ │         │
  └────┬────┘ └────┬────┘ └───────┘ └─────────┘ └─────────┘
       │            │
       └──────┬─────┘
              │
   ┌──────────▼──────────┐
   │    Service Layer     │
   │                      │
   │    loki_service      │
   └──────────┬──────────┘
              │
   ┌──────────▼──────────┐
   │   Loki HTTP API     │
   │   /loki/api/v1/*    │
   └─────────────────────┘

How it works:

1. An AI assistant connects via HTTP, SSE, or stdio.
2. The AI loads loki://system/health to verify Loki is reachable.
3. Tools follow a discovery-first workflow: labels → values → series → fields → stats → execute.
4. The service layer (loki_service) handles HTTP calls with connection pooling, auth injection, and response validation.
5. Middleware enforces rate limiting, response size caps, and structured logging.

Table of Contents

• Why Loki MCP Server?
• Key Features
• Architecture
• Tech Stack
• Getting Started
• Configuration
• Available Tools
• Available Resources
• Available Prompts
• Usage
• Project Structure
• Roadmap
• Contributing
• FAQ
• Troubleshooting
• Security Considerations
• License
• Contact
• Acknowledgments

Tech Stack

Getting Started

Prerequisites

• Docker (recommended) or Python 3.12+ (for local dev)
• Grafana Loki backend accessible via HTTP (default port: 3100)

Quick Start with Docker (recommended)

docker run --rm -it \
  -p 8770:8770 \
  -e MCP_TRANSPORT=http \
  -e LOKI_URL=http://host.docker.internal:3100 \
  talkopsai/loki-mcp-server:latest

The server is now listening on http://localhost:8770/mcp.

Point your MCP client at it:

{
  "mcpServers": {
    "loki": {
      "url": "http://localhost:8770/mcp",
      "description": "MCP Server for Grafana Loki log observability"
    }
  }
}

From Source (Python)

1. Install uv for dependency management.

2. Clone and set up:

git clone https://github.com/talkops-ai/talkops-mcp.git
cd talkops-mcp/src/loki-mcp-server
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

3. Configure your .env:

LOKI_URL=http://localhost:3100
MCP_TRANSPORT=http
MCP_LOG_LEVEL=INFO

4. Run the server:

uv run loki-mcp-server

Or, with the venv activated: loki-mcp-server.

5. Run tests:

source .venv/bin/activate
pytest tests/

Configuration

All configuration is via environment variables (loaded from .env via python-dotenv).

Server Configuration

Loki Backend

Authentication

Query Guardrails

Available Tools

Discovery

Structure

Safety

Execution

Available Resources

Dynamic Resources

Configuration Resources

Reference Resources (Static)

Available Prompts

Guided workflow prompts that orchestrate multiple tools into step-by-step journeys:

Usage

Supported workflows with prompt examples and links to detailed guides:

Project Structure

loki-mcp-server/
├── loki_mcp_server/               # Main package
│   ├── tools/                     # MCP Tools (4 groups, 8 tools)
│   │   ├── discovery/             # Label & series discovery
│   │   │   └── discovery_tools.py # 3 tools: get_cluster_labels, get_label_values, get_active_series
│   │   ├── structure/             # Log structure analysis
│   │   │   └── structure_tools.py # 2 tools: get_log_patterns, get_detected_fields
│   │   ├── safety/                # Query cost estimation
│   │   │   └── safety_tools.py    # 1 tool: get_query_stats
│   │   ├── execution/             # LogQL query execution
│   │   │   └── execution_tools.py # 3 tools: execute_logql_instant, execute_logql_query, loki_query_a2ui
│   │   ├── base.py                # Base tool class with service_locator DI
│   │   ├── registry.py            # Tool registry for lifecycle management
│   │   └── __init__.py            # initialize_tools factory
│   ├── resources/                 # MCP Resources (8 URIs)
│   │   ├── loki_resources.py      # System, config, and reference resources
│   │   └── base.py                # Base resource class
│   ├── prompts/                   # MCP Prompts (5 guided workflows)
│   │   ├── loki_prompts.py        # All prompt definitions
│   │   └── base.py                # Base prompt class
│   ├── services/                  # Business logic
│   │   └── loki_service.py        # Async HTTP client: all Loki API calls, auth injection,
│   │                              # connection pooling, response validation
│   ├── server/                    # FastMCP server setup
│   │   ├── core.py                # Server creation & instructions loading
│   │   ├── bootstrap.py           # Component initialization & DI (service_locator pattern)
│   │   └── middleware.py          # Middleware stack (error handling, logging, timing)
│   ├── models/                    # Pydantic data models
│   │   ├── common.py              # Shared model utilities
│   │   ├── schema.py              # Label schema models
│   │   ├── query.py               # Query response models
│   │   ├── patterns.py            # Pattern models
│   │   ├── stats.py               # Index stats models
│   │   └── detected_fields.py     # Detected fields models
│   ├── utils/                     # Helpers
│   │   ├── logql_helpers.py       # Stream selector validation, high-cardinality detection,
│   │   │                          # log entry formatting, parser suggestion
│   │   ├── time_utils.py          # Relative time parsing (now-1h → epoch), time window validation
│   │   └── pagination.py          # Cursor-based pagination utilities
│   ├── exceptions/                # Custom exception hierarchy
│   │   └── __init__.py            # LokiConnectionError, LokiQueryError, LokiQueryTooExpensiveError, etc.
│   ├── static/                    # Static reference files
│   │   ├── LOKI_MCP_INSTRUCTIONS.md  # MCP system instructions for AI agents
│   │   ├── logql_reference.md     # LogQL syntax guide
│   │   ├── best_practices.md      # Loki best practices
│   │   ├── query_templates.md     # Common LogQL query patterns
│   │   └── label_governance.md    # Label naming and cardinality governance
│   ├── config.py                  # Environment parsing & config dataclasses
│   └── main.py                    # Entry point & CLI
├── tests/                         # Test suites
│   ├── unit/                      # Unit tests (deterministic, mocked)
│   ├── integration/               # In-memory MCP integration tests
│   ├── fixtures/                  # Test fixtures (JSON responses)
│   └── conftest.py                # Shared test configuration
├── docs/                          # Documentation & test guides
├── pyproject.toml                 # Package definition (Python 3.12)
├── Dockerfile                     # Docker build
└── README.md                      # This documentation

Roadmap

Shipped in this release:

• Label taxonomy discovery with time-window scoping
• Label value enumeration with scope queries
• Active series validation with per-label cardinality and high-cardinality warnings
• Log pattern detection via Loki pattern ingester
• Detected field discovery (JSON/logfmt keys, types, cardinality, parsers)
• Preflight query cost estimation with configurable byte thresholds
• Unified LogQL execution for log streams and metric time-series
• Instant query execution for point-in-time scalar answers
• 5 guided workflow prompts (error investigation, health check, log structure, LogQL builder, schema exploration)
• 8 MCP resources (dynamic health/schema, config guardrails/backends, static references)
• Multi-tenancy with Bearer token, Basic Auth, and X-Scope-OrgID
• Middleware stack (error handling, response limiting, rate limiting, logging, timing)
• Configurable guardrails (max bytes, max time window, max log limit, cardinality threshold)
• High-cardinality label detection in stream selectors

Coming next:

• Log-to-trace correlation (extract trace IDs from log lines → pivot to Tempo MCP server)
• Multi-backend support (staging, production, multi-cluster)
• Loki ruler integration (alerting rule management)
• Log volume analysis (per-label byte usage trends)

See open issues for the full list of proposed features.

Contributing

Contributions are welcome. The process is straightforward:

1. Fork the repo
2. Create a branch (git checkout -b feature/LogStructureAnalysis)
3. Make your changes and commit
4. Push and open a PR

If you're considering something bigger, open an issue first so we can align on the approach.

FAQ

Troubleshooting

Loki Connection Issues

1. Verify LOKI_URL points to an accessible Loki HTTP endpoint (default port: 3100).
2. Load the loki://system/health resource to check Loki reachability.
3. For Loki behind a load balancer or gateway, verify the base URL routes to the query-frontend.
4. For authenticated backends, set LOKI_AUTH_TOKEN (Bearer) or LOKI_BASIC_AUTH_USER/LOKI_BASIC_AUTH_PASSWORD (Basic).

No Logs Found

1. Run get_cluster_labels() to verify data exists — if labels are returned, Loki has data.
2. Run get_label_values(label="app") to see available service names.
3. Broaden the time range: try start="now-24h" or start="now-7d".
4. Start with the broadest possible query: execute_logql_query(query='{app=~".+"}', start="now-1h", limit=5).
5. For multi-tenant deployments, verify the correct LOKI_ORG_ID is configured.

Detected Fields Endpoint Not Working

1. get_detected_fields requires Loki 3.0+ with the /loki/api/v1/detected_fields endpoint.
2. If you get a 404, your Loki version may not support this endpoint — upgrade Loki.
3. If fields are empty, logs may be unstructured (plain text without JSON/logfmt keys).

Pattern Ingester Not Working

1. get_log_patterns requires Loki's pattern ingester to be enabled.
2. In your Loki config: pattern_ingester: { enabled: true }.
3. Pattern data is ephemeral — typically covers the last 3 hours only.
4. If you get a 404, the pattern ingester is not enabled.

Query Too Expensive Errors

1. The execute_logql_query tool pre-checks query cost against LOKI_MAX_QUERY_BYTES.
2. Use get_query_stats first to estimate cost before executing.
3. Narrow the time range, add more specific selectors, or increase LOKI_MAX_QUERY_BYTES.

Security Considerations

• Never expose the MCP server to the public internet without proper authentication.
• All tools are read-only — the server only performs HTTP GET requests against Loki's query APIs. No data is created, modified, or deleted.
• Tenant isolation — in multi-tenant deployments, the server injects the X-Scope-OrgID header on every request. Verify that the org ID is correctly scoped to prevent cross-tenant data leakage.
• Auth credentials — if LOKI_AUTH_TOKEN or LOKI_BASIC_AUTH_PASSWORD is set, it is included in every request to the backend. Protect these values as secrets.
• Query guardrails — the server enforces byte, time window, limit, and cardinality thresholds to prevent unbounded queries. Review and adjust the guardrail settings for your environment.

License

Apache 2.0 — see LICENSE.

Contact

TalkOps AI — github.com/talkops-ai

Project: github.com/talkops-ai/talkops-mcp

Discord: Join the community

Acknowledgments

• Model Context Protocol for enabling AI-native tool interfaces.
• FastMCP for the Python MCP server framework.
• Grafana Loki for the scalable log aggregation system.
• OpenTelemetry for the industry-standard observability framework.