lgtm-mcp
========

A Model Context Protocol (MCP) server for the Grafana observability stack.
Connects AI agents to Prometheus, Loki, and Tempo through intent-based tools
over a stdio transport. Single binary, zero config beyond env vars.

Source: https://github.com/adarshba/lgtm-mcp


What is this?
-------------

lgtm-mcp exposes observability workflows as MCP tools. An AI agent (Claude,
Cursor, OpenCode, etc.) connects over stdio and calls tools that orchestrate
across metrics, logs, and traces to answer questions like "why is this service
slow?" or "what errors happened in the last 30 minutes?".

The LLM never sees raw PromQL, LogQL, or trace IDs. It calls intent-based
tools and gets back structured, summarised results.


Quick Start
-----------

  cargo install lgtm-mcp

  export PROMETHEUS_URL=http://localhost:9090
  export LOKI_URL=http://localhost:3100
  export TEMPO_URL=http://localhost:3200

  lgtm-mcp


Configuration
-------------

All configuration is via environment variables. No config file required.

  PROMETHEUS_URL        Base URL of your Prometheus instance
                        Default: http://localhost:9090

  LOKI_URL              Base URL of your Loki instance
                        Default: http://localhost:3100

  TEMPO_URL             Base URL of your Tempo instance
                        Default: http://localhost:3200

  PROMETHEUS_TOKEN      Bearer token for Prometheus auth (optional)
  LOKI_TOKEN            Bearer token for Loki auth (optional)
  TEMPO_TOKEN           Bearer token for Tempo auth (optional)

  REQUEST_TIMEOUT_SECS  HTTP request timeout in seconds
                        Default: 30

  RUST_LOG              Log level (error, warn, info, debug)
                        Default: info
                        Logs are written to stderr, never stdout.


MCP Client Setup
----------------

Add to your MCP client config (Claude Desktop, Cursor, OpenCode, etc.):

  {
    "mcpServers": {
      "lgtm": {
        "command": "lgtm-mcp",
        "env": {
          "PROMETHEUS_URL": "http://localhost:9090",
          "LOKI_URL": "http://localhost:3100",
          "TEMPO_URL": "http://localhost:3200"
        }
      }
    }
  }

For OpenCode CLI:

  {
    "lgtm": {
      "type": "local",
      "command": ["lgtm-mcp"],
      "environment": {
        "PROMETHEUS_URL": "http://localhost:9090",
        "LOKI_URL": "http://localhost:3100",
        "TEMPO_URL": "http://localhost:3200"
      },
      "enabled": true
    }
  }


Tools
-----

investigate_latency_spike  service, window_minutes
  Detects latency anomalies for a service. Fetches p50/p95/p99 from
  Prometheus, checks error rate, and surfaces the slowest traces from Tempo.
  Returns structured anomaly report with threshold reasoning.

find_errors  service, window_minutes
  Finds and deduplicates error logs for a service via Loki. Cross-references
  with Prometheus error rate. Returns top error messages with counts and
  associated trace IDs.

trace_slow_requests  service, window_minutes
  Searches Tempo for requests exceeding 1s. For each slow trace identifies
  the single bottleneck span. Returns trace IDs, durations, and span
  summaries — no raw payloads.

correlate_error_to_trace  error_id
  Takes an error ID or message substring, finds matching log entries in Loki,
  extracts the trace ID, and fetches the full trace from Tempo. Returns log
  context alongside trace summary with error spans highlighted.

summarize_service_health  service, window_minutes
  Full health snapshot: request rate (rps), error rate (%), p50/p95/p99
  latency, health classification (healthy/degraded/critical/unknown), and
  top recent error messages. Orchestrates Prometheus + Loki in parallel.


Service Labels
--------------

Tools match services using the label:

  service="<name>"

Ensure your Prometheus metrics, Loki streams, and Tempo traces all use this
label consistently. For Tempo, the attribute is service.name (OTLP standard).


Project Layout
--------------

  src/main.rs                      entry point, clap config, wires all layers
  src/transport/stdio.rs           JSON-RPC 2.0 over stdio (MCP protocol)
  src/backends/metrics.rs          Prometheus HTTP API client
  src/backends/logs.rs             Loki HTTP API client, trace_id extraction
  src/backends/traces.rs           Tempo HTTP API client, critical path analysis
  src/domain/mod.rs                cross-signal workflows, anomaly detection
  src/tools/mod.rs                 tool registry, schema definitions, dispatch


License
-------

MIT