talkopsai/tempo-mcp-server repository overview

⁠Tempo MCP Server by TalkOps.ai⁠

An MCP server that gives AI assistants the power to search, analyze, summarize, and correlate distributed traces from Grafana Tempo — with TraceQL query construction, RED metrics analysis, cross-pillar pivots, service topology mapping, and operational diagnostics.

⁠✨ Features

• Smart Trace Search: Translate K8s-friendly filters (namespace, service, deployment) into valid TraceQL, enforce query guardrails (time ranges, limits), and return compact trace summaries.
• Intelligent Trace Analysis: Fetch a trace, extract the critical path, identify error spans, detect the suspected root cause, and recommend follow-up queries — all in a single tool call.
• RED Metrics Triage: Execute TraceQL metrics queries (rate(), quantile_over_time(), count_over_time()) and pivot from aggregated metrics to concrete traces via exemplars.
• Cross-Pillar Correlation: Extract trace IDs from log lines and retrieve full traces. Pivot from metrics spikes to exemplar traces. Correlate related traces using multiple strategies.
• Backend Diagnostics: Aggregate health checks, build info, component service status, and ring member health into severity-ranked diagnostics with remediation steps.
• Service Topology: Map service dependencies from Tempo's metrics-generator service graph data, with request rates and error rates per edge.
• Multi-Tenancy: Per-backend tenant header injection (X-Scope-OrgID), cross-tenant queries, and tenant ID validation.
• Tempo Operator CRD Management: List, inspect, create, and patch TempoStack and TempoMonolithic custom resources with dry-run safety.

⁠🚀 How to Use This Image

This Docker image runs an MCP server that connects to your Grafana Tempo backend(s). AI assistants (Claude, Cline, Cursor, or any MCP client) connect to the server over HTTP, SSE, or stdio.

⁠Running Standalone (HTTP Transport)

docker run --rm -it \
  -p 8768:8768 \
  -e TEMPO_BASE_URL=http://host.docker.internal:3200 \
  -e MCP_TRANSPORT=http \
  talkopsai/tempo-mcp-server:latest

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

Then configure your MCP client to connect:

{
  "mcpServers": {
    "tempo": {
      "url": "http://localhost:8768/mcp",
      "description": "MCP Server for Grafana Tempo distributed tracing"
    }
  }
}

⁠With Kubernetes Discovery

To enable auto-discovery of Tempo backends via Kubernetes service labels and Tempo Operator CRDs:

docker run --rm -it \
  -p 8768:8768 \
  -v ~/.kube:/app/.kube:ro \
  -e TEMPO_BASE_URL=http://host.docker.internal:3200 \
  -e K8S_KUBECONFIG=/app/.kube/config \
  -e K8S_ENABLED=true \
  -e MCP_TRANSPORT=http \
  talkopsai/tempo-mcp-server:latest

⁠Multi-Backend Setup

Connect to multiple Tempo backends simultaneously:

docker run --rm -it \
  -p 8768:8768 \
  -e MCP_TRANSPORT=http \
  -e TEMPO_BACKENDS='[
    {"id": "prod", "base_url": "https://tempo-prod.example.com", "type": "tempo", "multi_tenant": true, "default_tenant": "team-a"},
    {"id": "staging", "base_url": "http://tempo-staging:3200", "type": "tempo"}
  ]' \
  talkopsai/tempo-mcp-server:latest

⁠🛠️ Configuration (Claude Desktop — Stdio)

To use this image over stdio transport directly inside Claude Desktop:

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

{
  "mcpServers": {
    "tempo-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TEMPO_BASE_URL=http://host.docker.internal:3200",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "MCP_LOG_LEVEL=INFO",
        "talkopsai/tempo-mcp-server:latest"
      ]
    }
  }
}

For multi-tenant backends, add tenant environment variables:

{
  "mcpServers": {
    "tempo-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TEMPO_BASE_URL=https://tempo.example.com",
        "-e", "TEMPO_MULTI_TENANT=true",
        "-e", "TEMPO_DEFAULT_TENANT=my-team",
        "-e", "TEMPO_AUTH_HEADER=Bearer your-token",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "MCP_LOG_LEVEL=INFO",
        "talkopsai/tempo-mcp-server:latest"
      ]
    }
  }
}

⁠⚙️ Environment Variables

⁠Server Configuration

⁠Tempo Backend (Single)

⁠Multi-Tenancy

⁠Query Guardrails

⁠LLM Format

⁠Kubernetes Discovery

⁠🔧 Available Tools (23 Total)

⁠Discovery

⁠Schema Discovery

⁠Search & Retrieval

⁠Metrics

⁠Cross-Pillar Pivots

⁠Diagnostics

⁠Topology

⁠Operator CRD Management

⁠Trace Comparison

⁠Alerting

⁠📖 Available Resources (11 URIs)

⁠🔐 Security Best Practices

1. Never expose the MCP server to the public internet without proper authentication.
2. All tools are read-only — the server only performs HTTP GET requests against Tempo's query APIs. No data is created, modified, or deleted.
3. Read-Only Mount: When using K8s discovery, always mount kubeconfig with :ro.
4. Tenant isolation: In multi-tenant deployments, verify tenant IDs are correctly scoped to prevent cross-tenant data leakage.
5. Protect auth headers: TEMPO_AUTH_HEADER is included in every request — treat it as a secret.
6. Query guardrails: The server enforces time range, limit, and filter requirements. Review and tune for your environment.
7. Operator CRD tools: tempo_create_operator_cr and tempo_patch_operator_cr default to dry_run=True. Review output before applying with dry_run=False.

⁠🐳 Docker Compose Example

services:
  tempo-mcp-server:
    image: talkopsai/tempo-mcp-server:latest
    ports:
      - "8768:8768"
    environment:
      - TEMPO_BASE_URL=http://tempo:3200
      - MCP_TRANSPORT=http
      - MCP_LOG_LEVEL=INFO
    depends_on:
      - tempo

  tempo:
    image: grafana/tempo:latest
    ports:
      - "3200:3200"
    command: -config.file=/etc/tempo/tempo.yaml
    volumes:
      - ./tempo.yaml:/etc/tempo/tempo.yaml

⁠🔗 Links and Resources

• Source Code: GitHub Repository⁠
• Full Documentation: README & Guides⁠
• Model Context Protocol: MCP Official Site⁠
• Grafana Tempo: Tempo Documentation⁠
• Tempo Operator: GitHub Repository⁠
• Report Issues: GitHub Issues⁠
• Discord: Join the Community⁠
• License: Apache 2.0⁠

If you find this MCP server useful, consider leaving a ⭐ on the GitHub repository⁠!