simple-tempo

This MCP server provides two primary tools designed to work with Grafana Tempo: tempo_query and tempo_trace_detail. tempo_query lets you search traces using intelligent query format detection, automatically handling TraceQL, tag-based queries, or simple service-name strings. tempo_trace_detail fetches detailed information for a specific trace ID. The server aims to produce human-readable results with clear context and proper URL encoding for all supported query formats. To use it, ensure TEMPO_URL is set to your Tempo frontend endpoint (via the environment variable TEMPO_URL or in your MCP config). Then run the server and issue queries through the tempo_query tool to retrieve traces and the tempo_trace_detail tool to drill into a given trace ID.

Prerequisites:\n- Go (1.16+) installed on your system to build the binary.\n- A Tempo instance accessible at TEMPO_URL.\n\nStep-by-step installation:\n1) Clone the repository or download the source code.\n2) Build the MCP server binary:\nbash\ngo build -o tempo-mcp-server ./cmd/server\n\n3) Place the binary somewhere your system can run it, for example: /usr/local/bin/tempo-mcp-server.\n4) Configure the TEMPO_URL environment variable to point at your Tempo instance, e.g.:\nbash\ TEMPO_URL=http://your-tempo:3200 ./tempo-mcp-server\n\n5) If you’re integrating with Claude Desktop, add the MCP server entry pointing to the binary path and TEMPO_URL as shown in the README example.\n\nNotes:\n- Ensure the Tempo endpoint is reachable from the host running the MCP server.\n- If you modify the code, rebuild using the go build command above.

Tips and common considerations:\n- TEMPO_URL defaults to http://localhost:3200 if not set, but it’s recommended to explicitly configure it.\n- The server auto-detects query formats (TraceQL, tags, service names) and handles URL encoding automatically for all supported query types.\n- Use the two core tools (tempo_query and tempo_trace_detail) for standard trace searches and targeted trace analysis.\n- When deploying with Claude Desktop, ensure the MCP config includes the server name (e.g., tempo) and the path to the binary, along with the TEMPO_URL env variable.\n- For network restrictions, consider running Tempo and the MCP server in the same network or ensure proper routing and TLS configuration if using https endpoints.\n- If you encounter encoding or parsing issues, verify that the query strings are properly formatted and that the Tempo endpoint is reachable from the MCP server host.