Skip to main content
Glama
Tempo MCP Server

Tempo MCP Server

by UjjwalSk

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

Related MCP server: LGTM MCP Server

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

Available Tools

6 tools
tempo_get_span_statisticsB

Get aggregated statistics for spans grouped by service, operation, or status. Returns count, avg/min/max/percentile durations.

Inputs: end, tags, limit, query, +2 more.

tempo_get_traceB

Get complete trace data by trace ID, including all spans with full details

Inputs: traceId (required).

tempo_get_trace_spansB

Get all spans from a specific trace with optional filtering by service name, span name, duration, attributes, or error status

Inputs: traceId (required), hasError, spanName, attributes, +3 more.

tempo_query_by_tagB

Convenience method to query traces by specific tag/attribute filters. Useful for filtering by sometag, user.id, environment, etc.

Inputs: tagFilters (required), end, limit, start, +3 more.

tempo_search_spansC

Search for traces and return all matching spans across multiple traces with filtering. Useful for finding specific operations across your system.

Inputs: end, tags, limit, query, +9 more.

tempo_search_tracesA

Search traces using TraceQL query language. Automatically handles various query syntax formats. The query parser will normalize your query to work with Tempo. Default time range: last 7 days.

Inputs: end, tags, limit, query, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 6 tools

    Disambiguation4/5

    The tools are largely distinct: get_trace (full trace), search_traces (TraceQL), get_trace_spans (spans within a trace), search_spans (spans across traces), get_span_statistics (aggregations), query_by_tag (tag-based queries). The main overlap is between search_traces and query_by_tag—both retrieve traces—but the tool descriptions clarify their inputs. This is a modest overlap, not a severe one.

    Naming Consistency4/5

    Naming follows a consistent pattern of tempo_ followed by action_noun: tempo_get_trace, tempo_search_traces, tempo_get_trace_spans, tempo_search_spans, tempo_get_span_statistics, tempo_query_by_tag. The verb/noun structure is uniform across all tools, making the API predictable. tempo_query_by_tag uses 'query' instead of 'search', a minor deviation, but overall the pattern is clear and consistent.

    Tool Count5/5

    Six tools is a well-scoped set for a tracing query server. Each tool serves a distinct purpose: retrieving full traces, searching by query language, filtering spans, cross-trace span search, aggregations, and tag-based lookup. None feel redundant or unnecessary; the count is right for the domain scope.

    Completeness4/5

    The server covers trace lookup, searching (by TraceQL and tags), span retrieval, and statistics—a solid coverage of Tempo's core tracing query workflows. Missing operations like trace comparison or raw query execution are minor; the surface is reasonably complete for its domain. A notable gap is no direct capability to fetch recent traces without a query, relying on search having sensible defaults.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language querying and analysis of OpenTelemetry traces, metrics, and logs stored in Elasticsearch/OpenSearch, allowing AI assistants to investigate performance issues, find root causes, and explore system behavior.
      22 npm
      14
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides read-only access to Loki, Prometheus, and Tempo APIs, enabling natural language queries for logs, metrics, and traces. Supports multiple instances and authentication via bearer tokens.
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Connects AI assistants to OpenTelemetry trace backends (Jaeger, Grafana Tempo, Traceloop, Datadog, Sentry, AWS X-Ray, New Relic and Honeycomb) for natural-language trace and span search, error triage, cross-backend correlation, and LLM analytics such as token usage, model performance and the most expensive or slowest traces.
      19
      172 PyPI
      1
      Apache 2.0
    • A
      license
      B
      quality
      C
      maintenance
      Enables developers to investigate request failures by querying Prometheus metrics, Loki logs, and Tempo traces without opening Grafana, while supporting read-only access and optional Grafana annotations.
      11
      MIT