Tempo MCP Server

🚀 Tempo MCP Server

A Go-based server implementation for integrating the Model Context Protocol (MCP) with Grafana Tempo.

🚀 Quick Start

This MCP server allows AI assistants to query and analyze distributed tracing data from Grafana Tempo. It adheres to the Model Context Protocol (MCP) for use with compatible AI clients, such as Claude Desktop.

Prerequisites

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

Build and Run

Build and run the server:

# Build the project
go build

# Run the server
./tempo-mcp-server

✨ Features

Server Endpoints

• HTTP Endpoint: http://localhost:8080
• WebSocket Endpoint: ws://localhost:8080/ws

Docker Support

You can build and run the project as a Docker image using the following commands:

# Build the Docker image
docker build -t tempo-mcp-server .

# Run the Docker container
docker run -p 8080:8080 tempo-mcp-server

Project Structure

Here is the project's directory structure:

tempo-mcp-server/
├── main.go                 # Main program entry
├── server.go               # Server implementation
├── handler.go              # Request handling logic
└── docker/Dockerfile      # Docker configuration file

MCP Server

Tool Definitions

Here are the tools supported by the MCP server and their details:

tempo_query

• Description: Used to query tracing data from Grafana Tempo.
• Required Parameters:
  • query: The query statement to execute.
• Optional Parameters:
  • limit: Limit the number of returned results (default value is 10).

Environment Variables

The following environment variables affect the server's behavior:

• TEMPO_SERVER_ADDR: Specify the server's listening address (default value is localhost:8080).
• TEMPO_SERVER_DEBUG: Enable debug mode (default value is false).

Testing

You can run tests using the following command:

go test ./...

Integration with Claude Desktop

To integrate the Tempo MCP server with Claude Desktop, follow these steps:

1. Open Claude Desktop's configuration file.
2. Add the following content to the mcpServers section:

{
  "tempo-mcp-server": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "-e", "TEMPO_URL=http://host.docker.internal:8080", "tempo-mcp-server:latest"]
  }
}

3. Save the file and restart Claude Desktop.

Integration with Cursor

To use the Tempo MCP server in Cursor, follow these steps:

1. Open Cursor's settings.
2. Add the following content to the mcpServers section:

{
  "tempo-mcp-server": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "-e", "TEMPO_URL=http://host.docker.internal:8080", "tempo-mcp-server:latest"]
  }
}

3. Save the settings.

Integration with n8n

To integrate the Tempo MCP server with n8n, follow these steps:

1. Add an MCP Client Tool node in n8n.
2. Configure the node as follows:

• SSE Endpoint: http://your-server-address:8080/sse
• Authentication: Select an appropriate authentication method.
• Included Tools: Select the tools to expose to the AI agent.

3. Connect the MCP Client Tool node to a supported AI agent node (e.g., Claude).

Usage Examples

After configuration, you can use the following queries in Claude:

• "Query tracing data from Tempo using {duration>1s}."
• "Find tracing records of the frontend service in Tempo using the query {service.name=\"frontend\"}."
• "Show the latest 50 Tempo tracing records that satisfy {http.status_code=500}."

📄 License

This project is released under the MIT License.