Tempo MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Tempo MCP Server Show traces with HTTP 500 errors in the last hour"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 buildConfiguration
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=30000Claude 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 IDserviceName(string): Filter by service namespanName(string): Filter by span name (partial match)minDuration(number): Min span duration in msmaxDuration(number): Max span duration in mshasError(boolean): Filter error spans onlyattributes(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,endSpan 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,endgroupBy(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 pairsserviceName(string): Service name filterminDuration,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 startTroubleshooting
Connection Issues
Verify
TEMPO_URLis correctCheck Tempo is running:
curl http://localhost:3200/api/statusCheck 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.nameinstead of.service.namefor service filteringFor debugging, set
TEMPO_DEBUG=truein environment
Performance
Reduce
limitparameter for faster queriesNarrow time ranges
Use specific filters to reduce data volume
Available Tools
6 toolstempo_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
Scored across 6 tools
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 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.
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.
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
Related MCP Connectors
Query Honeycomb observability data: traces, events, metrics, SLOs, triggers, and boards.
Query Telemetry Machine observability data and instrument your apps with OpenTelemetry.
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Access New Relic observability data through MCP - query metrics, logs, traces, entities, and more
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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 npm14MIT
- AlicenseNot gradedqualityDmaintenanceProvides 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.1MIT
- AlicenseAqualityBmaintenanceConnects 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.19172 PyPI1Apache 2.0
- AlicenseBqualityCmaintenanceEnables 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.11MIT