Tempo MCP Server for Grafana Trace Queries

Overview

Tempo MCP Server provides an MCP-compatible HTTP endpoint that queries Grafana Tempo for traces and spans. Instead of calling Tempo directly from an application or LLM integration, you deploy this lightweight adapter that accepts structured requests (filters, time ranges, span attributes) and returns matching trace context and span data in a compact JSON form. The server is intended to speed up common trace lookups and simplify filtering logic for downstream tooling.

This is useful when you want fast, programmatic access to Tempo data for observability workflows, incident analysis, or LLM-based assistance. By centralizing Tempo query logic behind a small server, you can cache, normalize, and restrict queries while providing a stable, MCP-oriented API to clients.

GitHub: https://github.com/scottlepp/tempo-mcp-server

Features

• Query Tempo traces and spans using filterable criteria (trace ID, service, span name, time range, duration).
• Lightweight MCP server interface suitable for integration with LLMs and orchestration tools.
• Configurable connection to Grafana Tempo (URL, auth, timeouts).
• Result shaping to return only the fields required by the consumer (e.g., span name, start, duration, attributes).
• Simple CLI and Docker-friendly deployment.

Installation / Configuration

Prerequisites: Go 1.18+ to build from source, or Docker to run as a container.

Clone and build from source:

git clone https://github.com/scottlepp/tempo-mcp-server.git
cd tempo-mcp-server
go build -o tempo-mcp-server ./cmd/tempo-mcp-server

Run the binary:

./tempo-mcp-server \
  --tempo-url "http://tempo:3100" \
  --listen ":8080" \
  --timeout "10s" \
  --max-results 100

Docker example:

docker run -p 8080:8080 \
  -e TEMPO_URL="http://tempo:3100" \
  -e LISTEN_ADDR=":8080" \
  -e MAX_RESULTS=100 \
  ghcr.io/your-org/tempo-mcp-server:latest

Configuration options (common flags / environment variables):

Note: If your Tempo instance requires authentication, configure it via standard HTTP headers or reverse proxy in front of Tempo. The server exposes a simple HTTP client; extend or modify it to include API keys or basic auth if needed.

Available Resources

• Repository: https://github.com/scottlepp/tempo-mcp-server
• Grafana Tempo HTTP API docs: https://grafana.com/docs/tempo/latest/api/ (refer when building complex filters)
• MCP (Model Context Protocol) references or consumer docs (check your LLM client library for exact request shapes)

Use Cases

1. Query by Trace ID

   • Problem: Your alert includes a trace ID. You want the full trace with spans to show context in an incident ticket or chat assistant.
   • Example:

     curl -X POST http://localhost:8080/query \
       -H "Content-Type: application/json" \
       -d '{"trace_id":"1234abcd..."}'
     

     Response includes trace-level metadata and ordered spans.

2. Filter by Service and Span Name

   • Problem: Find slow spans for a specific service within the last 30 minutes.
   • Example:

     curl -X POST http://localhost:8080/query \
       -H "Content-Type: application/json" \
       -d '{
         "service": "payments",
         "span_name": "ProcessPayment",
         "start": "2026-04-10T10:00:00Z",
         "end": "2026-04-10T10:30:00Z",
         "min_duration_ms": 500
       }'
     

     The server returns spans matching the filters, allowing downstream tools to surface only the slow operations.

3. Augment LLM Prompts with Trace Context

   • Problem: Provide an LLM with concise trace and span summaries for troubleshooting prompts.
   • Workflow:
     • LLM asks the MCP server for relevant spans (service, error flags, top attributes).
     • The MCP server returns filtered, concise JSON that the LLM can embed directly into its prompt.

4. Automated Incident Triage

   • Problem: A CI job detects elevated error rates; an automation pipeline needs to collect traces for root cause analysis.
   • Example flow:
     • Pipeline calls the MCP server to fetch traces for the affected service and time window.
     • Results are saved to an incident runbook or passed into further analyzers.

Tips for Developers

• Keep queries narrow (service, time range, duration) to avoid large result sets; use max-results to protect the Tempo backend.
• Cache frequent queries in front of the MCP server if you expect repeated lookups from chat assistants or dashboards.
• If you plan to expose the server publicly, add authentication and rate limiting to prevent abuse.
• Consult Grafana Tempo’s API when building advanced filters (attribute queries, join-like aggregation).

If you need additional examples or a reference integration (LLM or alerting pipeline), check the repository for sample clients and the source code for request/response shapes.