Grafana Tempo

A simple, working MCP (Model Context Protocol) server for Grafana Tempo with intelligent query format detection and enhanced trace analysis.

🚀 Why This Implementation Works Better

This implementation addresses critical issues found in the official Grafana tempo-mcp-server:

• 🧠 Intelligent Query Detection: Automatically detects TraceQL, tags, or service name formats
• ✅ Correct URL Encoding: Proper URL encoding for all query types
• 📊 Human-Readable Responses: Structured output with emojis and context
• ⏰ Flexible Time Handling: Unix timestamps, relative times (-1h), RFC3339, "now"

🔧 Features

Two Powerful Tools

• tempo_query: Search traces with intelligent format detection
• tempo_trace_detail: Get detailed trace information by trace ID

Query Examples

# TraceQL (auto-detected by {} brackets)
{service.name="payment-service" && duration>1s}

# Service name (auto-detected as simple string)
payment-service

# Tags format (auto-detected by = sign)
service.name=payment-service

🚀 Quick Start

# Build the binary
go build -o tempo-mcp-server ./cmd/server

# Run with your Tempo instance
TEMPO_URL=http://your-tempo:3200 ./tempo-mcp-server

⚙️ MCP Configuration

Claude Desktop Configuration

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "tempo": {
      "command": "/path/to/tempo-mcp-server",
      "env": {
        "TEMPO_URL": "http://your-tempo:3200"
      }
    }
  }
}

Environment Variables

• TEMPO_URL: Your Tempo query-frontend endpoint (default: http://localhost:3200)

🎯 Usage Examples

Query Examples

# Find slow traces
{duration>1s}

# Service-specific errors  
{service.name="payment-service" && status=error}

# HTTP errors
{http.status_code>=400}

# Simple service name
payment-service

Time Range Examples

start: "-1h"        # 1 hour ago
start: "-6h"        # 6 hours ago  
start: "1754541396" # Unix timestamp
end: "now"          # Current time

🆚 Why This Works vs Official Grafana Version

Issue	This Implementation	Official Grafana
Query Format	🧠 Auto-detects TraceQL/tags/service	❌ Manual format specification
URL Encoding	✅ Automatic & correct	⚠️ Encoding issues
Response Format	📊 Human-readable	📄 Raw JSON
Error Handling	🛡️ Detailed context	❓ Generic errors

📄 License

MIT License - see LICENSE file for details.

---

⭐ Simple, working Tempo MCP server that just works with Claude Desktop!