LGTM MCP Server

MCP server providing read-only access to Loki, Prometheus, and Tempo APIs.

Features

• Multi-instance support: Configure multiple LGTM stacks and switch between them
• Bearer token authentication: Works with Grafana Cloud and self-hosted deployments
• Query tools: Execute LogQL, PromQL, and TraceQL queries
• Metadata discovery: Expose labels, metrics, and tags as MCP resources
• Syntax documentation: Built-in query language references
• OpenTelemetry tracing: All HTTP client calls are traced and exported via OTLP/gRPC

Configuration

Create a config file at ~/.config/lgtm-mcp/config.yaml:

version: "1"
default_instance: "local"

instances:
  local:
    loki:
      url: "http://localhost:3100"
    prometheus:
      url: "http://localhost:9090"
    tempo:
      url: "http://localhost:3200"

  grafana-cloud:
    loki:
      url: "https://logs-prod-us-west-0.grafana.net"
      username: "${GRAFANA_CLOUD_LOKI_USERNAME}"
      token: "${GRAFANA_CLOUD_TOKEN}"
    prometheus:
      url: "https://prometheus-prod-01-us-west-0.grafana.net/api/prom"
      username: "${GRAFANA_CLOUD_PROMETHEUS_USERNAME}"
      token: "${GRAFANA_CLOUD_TOKEN}"
    tempo:
      url: "https://tempo-prod-us-west-0.grafana.net"
      username: "${GRAFANA_CLOUD_TEMPO_USERNAME}"
      token: "${GRAFANA_CLOUD_TOKEN}"

Environment variables are expanded using ${VAR} syntax.

For Grafana Cloud, a token with read-only permissions is sufficient. See Creating access policies for details.

Usage

Claude Code

Add the MCP server using the Claude Code CLI:

claude mcp add lgtm -- uvx --from git+https://github.com/pokgak/lgtm-mcp lgtm-mcp

Or manually add to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "lgtm": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/pokgak/lgtm-mcp", "lgtm-mcp"]
    }
  }
}

Claude Desktop

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "lgtm": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/pokgak/lgtm-mcp", "lgtm-mcp"]
    }
  }
}

Local Development

If you've cloned the repository locally:

{
  "mcpServers": {
    "lgtm": {
      "command": "uv",
      "args": ["run", "lgtm-mcp"],
      "cwd": "/path/to/lgtm-mcp"
    }
  }
}

Available Tools

Loki (Logs)

• loki_patterns - Start here! Detect log patterns and frequency (requires pattern_ingester enabled)
• loki_stats - Get quick stats (stream count, bytes) without fetching logs
• loki_volume - Get log volume breakdown by labels
• loki_query_logs - Retrieve log entries (use after patterns to get specific examples)
• loki_instant_query - Metric-type LogQL at single point
• loki_get_labels - List label names
• loki_get_label_values - Get values for a label
• loki_get_series - Find matching log streams

Prometheus (Metrics)

• prometheus_instant_query - Execute PromQL instant query
• prometheus_range_query - Execute PromQL range query (broken)
• prometheus_range_query_chart - Range query with ASCII chart visualization
• prometheus_get_metric_names - List metrics
• prometheus_get_label_names - List label names
• prometheus_get_label_values - Get values for a label
• prometheus_get_series - Find matching series
• prometheus_get_metadata - Get metric metadata

Tempo (Traces)

• tempo_trace_summary - Start here! Get trace summary with stats (duration p50/p95/p99, error count, span tree)
• tempo_get_trace - Retrieve full trace data (use after summary for details)
• tempo_search_traces - Search with TraceQL
• tempo_get_tag_names - List tag names
• tempo_get_tag_values - Get values for a tag
• tempo_get_services - List service names

Utility

• list_instances - List configured instances
• set_default_instance - Change default instance

Available Resources

Resources expose metadata for query generation:

• lgtm://{instance}/loki/labels - Loki label names
• lgtm://{instance}/prometheus/labels - Prometheus label names
• lgtm://{instance}/prometheus/metrics - Metric names
• lgtm://{instance}/tempo/tags - Tempo tag names
• lgtm://syntax/logql - LogQL syntax reference
• lgtm://syntax/promql - PromQL syntax reference
• lgtm://syntax/traceql - TraceQL syntax reference

Tracing

The server automatically instruments all HTTP client calls with OpenTelemetry. Traces are exported via OTLP/gRPC.

By default, traces are sent to http://localhost:4317. Override with:

export OTEL_EXPORTER_OTLP_ENDPOINT="http://your-collector:4317"

Service name: lgtm-mcp

Development

# Install with dev dependencies
uv pip install -e ".[dev]"

# Run type checks
mypy src/

# Run linter
ruff check src/

# Run tests
pytest