Tempo MCP Server

An advanced Model Context Protocol (MCP) server for querying Grafana Tempo traces and spans with comprehensive filtering capabilities.

Features

• Flexible Trace Search: Query traces using TraceQL or legacy tags
• Span Filtering: Filter spans by service name, duration, attributes, errors
• Detailed Span Analysis: Get complete span details with calculated durations
• Span Statistics: Aggregate statistics grouped by service/operation/status
• Tag-based Queries: Easy filtering by custom tags
• Time Range Support: Query by absolute or relative time ranges
• Duration Filtering: Filter by min/max duration at trace and span level

Installation

cd ~/tempo-mcp-server
npm install
npm run build

Configuration

Environment Variables

Create a .env file or set environment variables:

# Required
TEMPO_URL=http://localhost:3200

# Optional
TEMPO_USERNAME=admin
TEMPO_PASSWORD=secret
TEMPO_TOKEN=bearer_token_here
TEMPO_TIMEOUT=30000

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "tempo-mcp": {
      "command": "node",
      "args": ["[YOUR-PROJECT-PATH]/dist/index.js"],
      "env": {
        "TEMPO_URL": "http://localhost:3200"
      }
    }
  }
}

Available Tools

1. tempo_search_traces

Search traces with flexible filtering options.

Parameters:

• query (string): TraceQL query (e.g., {.service.name="app-demo"})
• tags (string): Legacy tags format (e.g., service.name=app-demo)
• minDuration (string): Minimum duration (e.g., "100ms", "1s")
• maxDuration (string): Maximum duration (e.g., "5s")
• limit (number): Max traces to return (default: 20)
• start (string): Start time (RFC3339 or Unix timestamp)
• end (string): End time (RFC3339 or Unix timestamp)

Example:

{
  "query": "{.service.name=\"app-demo\" && span.http.status_code >= 400}",
  "minDuration": "100ms",
  "limit": 50,
  "start": "2025-01-01T00:00:00Z"
}

2. tempo_get_trace

Get complete trace data by ID.

Parameters:

• traceId (string, required): The trace ID

3. tempo_get_trace_spans

Get all spans from a trace with optional filtering.

Parameters:

• traceId (string, required): The trace ID
• serviceName (string): Filter by service name
• spanName (string): Filter by span name (partial match)
• minDuration (number): Min span duration in ms
• maxDuration (number): Max span duration in ms
• hasError (boolean): Filter error spans only
• attributes (object): Filter by attributes (e.g., {"http.method": "POST"})

Example:

{
  "traceId": "1c4090cb9c90630901b167ad22c769aa",
  "serviceName": "app-demo",
  "minDuration": 100,
  "attributes": {
    "http.method": "POST"
  }
}

4. tempo_search_spans

Search traces and return matching spans across multiple traces.

Parameters:

• Trace search params: query, tags, minDuration, maxDuration, limit, start, end
• Span filter params: serviceName, spanName, spanMinDuration, spanMaxDuration, spanHasError, spanAttributes

Example:

{
  "query": "{.service.name=\"app-demo\"}",
  "limit": 10,
  "spanName": "POST",
  "spanMinDuration": 1000
}

5. tempo_get_span_statistics

Get aggregated span statistics.

Parameters:

• Search params: query, tags, limit, start, end
• groupBy (string): "service", "operation", or "status"

Returns:

• Count, avg/min/max durations, p50/p95/p99 percentiles per group

Example:

{
  "query": "{.service.name=\"app-demo\"}",
  "limit": 100,
  "groupBy": "service"
}

6. tempo_query_by_tag

Query traces by custom tag filters (convenience method).

Parameters:

• tagFilters (object, required): Tag key-value pairs
• serviceName (string): Service name filter
• minDuration, maxDuration, limit, start, end

Example:

{
  "tagFilters": {
    "customtag": "tagValue",
    "environment": "production"
  },
  "limit": 20
}

Usage Examples

Example 1: Find all traces for a custom tag

tempo_query_by_tag({
  tagFilters: { "customtag": "tagValue" },
  start: "2025-01-01T00:00:00Z",
  end: "2025-01-02T00:00:00Z"
})

Example 2: Get detailed span breakdown

tempo_get_trace_spans({
  traceId: "abc123...",
  serviceName: "app-demo"
})

Example 3: Find slow database operations

tempo_search_spans({
  query: "{.service.name=\"app-demo\"}",
  spanName: "SELECT",
  spanMinDuration: 1000  // > 1 second
})

Example 4: Get service performance statistics

tempo_get_span_statistics({
  query: "{.service.name=\"app-demo\"}",
  start: "2025-01-01T00:00:00Z",
  groupBy: "operation"
})

Example 5: Find errors in a time range

tempo_search_traces({
  query: "{span.http.status_code >= 400}",
  start: "1704067200",  // Unix timestamp
  limit: 50
})

TraceQL Query Examples

// By service name
{.service.name="app-demo"}

// By tag
{.customtag="tagValue"}

// HTTP status codes
{span.http.status_code >= 400}

// Duration
{duration > 1s}

Time Format Examples

// RFC3339
"2025-01-01T00:00:00Z"
"2025-01-01T00:00:00+05:30"

// Unix timestamp (seconds)
"1704067200"
1704067200

// Relative (in TraceQL)
"now-1h"
"now-24h"

Development

# Watch mode
npm run watch

# Build
npm run build

# Run
npm start

Troubleshooting

Connection Issues

• Verify TEMPO_URL is correct
• Check Tempo is running: curl http://localhost:3200/api/status
• Check firewall/network connectivity

Query Errors

• Validate TraceQL syntax - queries must be wrapped in {}
• Check time range is valid (RFC3339 or Unix seconds)
• Ensure trace IDs are correct format (hex string)
• Use resource.service.name instead of .service.name for service filtering
• For debugging, set TEMPO_DEBUG=true in environment

Performance

• Reduce limit parameter for faster queries
• Narrow time ranges
• Use specific filters to reduce data volume