simple-tempo-mcp-server

🚀 简单Tempo MCP服务器

这是一个简单且实用的MCP（模型上下文协议）服务器，专为Grafana Tempo设计，具备智能查询格式检测和增强的跟踪分析功能。它能有效解决在实际使用中遇到的问题，为用户提供更便捷、高效的使用体验。

🚀 快速开始

# 构建二进制文件
go build -o tempo-mcp-server ./cmd/server

# 使用你的Tempo实例运行
TEMPO_URL=http://your-tempo:3200 ./tempo-mcp-server

✨ 主要特性

两个强大的工具

• tempo_query：通过智能格式检测搜索跟踪信息。
• tempo_trace_detail：通过跟踪ID获取详细的跟踪信息。

查询示例

# TraceQL（通过{}括号自动检测）
{service.name="payment-service" && duration>1s}

# 服务名称（作为简单字符串自动检测）
payment-service

# 标签格式（通过=符号自动检测）
service.name=payment-service

📦 安装指南

Claude桌面配置

将以下内容添加到你的Claude桌面配置文件中：

• 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"
      }
    }
  }
}

环境变量

• TEMPO_URL：你的Tempo查询前端端点（默认：http://localhost:3200）

💻 使用示例

查询示例

# 查找慢速跟踪
{duration>1s}

# 特定服务的错误
{service.name="payment-service" && status=error}

# HTTP错误
{http.status_code>=400}

# 简单服务名称
payment-service

时间范围示例

start: "-1h"        # 1小时前
start: "-6h"        # 6小时前
start: "1754541396" # Unix时间戳
end: "now"          # 当前时间

📚 详细文档

为何此实现效果更佳

此实现解决了官方Grafana tempo-mcp-server中发现的关键问题：

• 🧠 智能查询检测：自动检测TraceQL、标签或服务名称格式。
• ✅ 正确的URL编码：对所有查询类型进行正确的URL编码。
• 📊 人类可读的响应：带有表情符号和上下文的结构化输出。
• ⏰ 灵活的时间处理：支持Unix时间戳、相对时间（-1h）、RFC3339、“now”。

与官方Grafana版本的对比

| 问题 | 本实现 | 官方Grafana | |-------|-------------------|------------------| | 查询格式 | 🧠 自动检测TraceQL/标签/服务 | ❌ 手动指定格式 | | URL编码 | ✅ 自动且正确 | ⚠️ 编码问题 | | 响应格式 | 📊 人类可读 | 📄 原始JSON | | 错误处理 | 🛡️ 详细上下文 | ❓ 通用错误 |

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

⭐ 简单实用的Tempo MCP服务器，可直接与Claude桌面配合使用！