tempo

The Tempo MCP Server is a Go-based implementation of the Model Context Protocol (MCP) with Grafana Tempo integration. It exposes a tempo_query tool that lets clients query Grafana Tempo trace data via MCP-compatible tooling, making it possible to retrieve and analyze distributed traces within AI-assisted workflows. The server can operate in two modes: a standard MCP over stdin/stdout and an HTTP/SSE endpoint for real-time streaming and integration with tools like Claude Desktop, n8n, or Cursor. When running in HTTP mode, the default SSE port is 8080 and can be customized with the SSE_PORT environment variable.

To use the server, run it (via Go) and then invoke the tempo_query tool (or expose it to your agent via Claude Desktop, Cursor, or n8n). The tempo_query tool accepts a required Tempo query string and optional parameters such as tempo URL, time range, result limits, and authentication credentials. Typical queries look like {service.name="frontend"} or {duration>1s}. The server will forward these queries to Grafana Tempo and return matching traces for analysis by the AI agent.

Prerequisites:

• Go 1.21 or higher
• Docker and Docker Compose (optional, for local testing)

Install and run from source:

1. Ensure Go is installed and in PATH.

2. Clone the repository and navigate to it.

3. Build the server binary:

   go build -o tempo-mcp-server ./cmd/server

4. Run the server locally:

   ./tempo-mcp-server

Alternatively, run directly with Go:

go run ./cmd/server

Configure runtime options as needed via environment variables, for example:

• TEMPO_URL: Tempo server URL (default: http://localhost:3200)
• SSE_PORT: Port for the HTTP/SSE server (default: 8080)

If you prefer Docker for local testing, you can build and run a Docker image (as described in the README):

docker build -t tempo-mcp-server . docker run -p 8080:8080 --rm -i tempo-mcp-server

Notes and tips:

• The Tempo MCP Server supports two communication modes: MCP over stdin/stdout and HTTP/SSE. Use the SSE endpoints if you plan to connect with Claude Desktop, n8n, or Cursor.
• The Tempo query tool requires at least the 'query' parameter. Optional params include 'url', 'start', 'end', 'limit', 'username', 'password', and 'token'.
• Environment variables TEMPO_URL and SSE_PORT influence default behavior when not explicitly provided per-request.
• If you run via Claude Desktop or Cursor, you may need to provide a path to the server binary or a Docker image with appropriate environment variables (e.g., TEMPO_URL).
• Since the project is archived, consider using the Tempo repository’s embedded MCP server for internal reference or testing, and align any integration with the Tempo MCP definitions there.