Tempo MCP 服务器

一个基于 Go 的服务器实现，用于支持集成 Grafana Tempo 的模型上下文协议 (MCP)。

概述

此 MCP 服务器允许 AI 助手查询和分析来自 Grafana Tempo 的分布式追踪数据。它遵循模型上下文协议，以提供可由兼容的 AI 客户端（如 Claude Desktop）使用的工具定义。

快速开始

前提条件

• Go 1.21 或更高版本
• Docker 和 Docker Compose（用于本地测试）

构建和运行

构建并运行服务器：

# 构建服务器
go build -o tempo-mcp-server ./cmd/server

# 运行服务器
./tempo-mcp-server

或者直接使用 Go 运行：

go run ./cmd/server

服务器使用 stdin/stdout 进行通信，遵循模型上下文协议 (MCP)。 这使其适合与 Claude Desktop 和其他 MCP 兼容的客户端一起使用。 它不作为 HTTP 服务器在端口上运行。

Docker 支持

您可以使用 Docker 构建和运行 MCP 服务器：

# 构建 Docker 镜像
docker build -t tempo-mcp-server .

# 运行服务器
docker run --rm -i tempo-mcp-server

或者，您可以使用 Docker Compose 来获得完整的测试环境：

# 使用 Docker Compose 构建和运行
docker-compose up --build

项目结构

.
├── cmd/
│   ├── server/       # MCP 服务器实现
│   └── client/       # 用于测试 MCP 服务器的客户端
├── internal/
│   └── handlers/     # 工具处理程序
├── pkg/
│   └── utils/        # 实用函数和共享代码
└── go.mod            # Go 模块定义

MCP 服务器

Tempo MCP 服务器实现了模型上下文协议 (MCP) 并提供以下工具：

Tempo 查询工具

tempo_query 工具允许您查询 Grafana Tempo 追踪数据：

• 必需参数：
  • query: Tempo 查询字符串（例如，{service.name="frontend"}，{duration>1s}）
• 可选参数：
  • url: Tempo 服务器 URL（默认：来自 TEMPO_URL 环境变量或 http://localhost:3200）
  • start: 查询的开始时间（默认：1 小时前）
  • end: 查询的结束时间（默认：现在）
  • limit: 要返回的最大追踪数（默认：20）
  • username: 用于基本身份验证的用户名（可选）
  • password: 用于基本身份验证的密码（可选）
  • token: 用于身份验证的 Bearer 令牌（可选）

环境变量

Tempo 查询工具支持以下环境变量：

• TEMPO_URL: 如果请求中未指定，则使用的默认 Tempo 服务器 URL

测试

./run-client.sh tempo_query "{resource.service.name=\\\"example-service\\\"}"

与 Claude Desktop 一起使用

您可以将此 MCP 服务器与 Claude Desktop 一起使用，以添加 Tempo 查询工具。 请按照以下步骤操作：

1. 构建服务器或 Docker 镜像
2. 通过将其添加到您的 Claude Desktop 配置文件，配置 Claude Desktop 以使用该服务器

Claude Desktop 配置示例：

{
  "mcpServers": {
    "temposerver": {
      "command": "path/to/tempo-mcp-server",
      "args": [],
      "env": {
        "TEMPO_URL": "http://localhost:3200"
      },
      "disabled": false,
      "autoApprove": ["tempo_query"]
    }
  }
}

对于 Docker：

{
  "mcpServers": {
    "temposerver": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "TEMPO_URL=http://host.docker.internal:3200", "tempo-mcp-server"],
      "disabled": false,
      "autoApprove": ["tempo_query"]
    }
  }
}

Claude Desktop 配置文件位于：

• 在 macOS 上：~/Library/Application Support/Claude/claude_desktop_config.json
• 在 Windows 上：%APPDATA%\Claude\claude_desktop_config.json
• 在 Linux 上：~/.config/Claude/claude_desktop_config.json

与 Cursor 一起使用

您还可以将 Tempo MCP 服务器与 Cursor 编辑器集成。 为此，请将以下配置添加到您的 Cursor 设置：

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

使用示例

配置完成后，您可以在 Claude 中使用这些工具进行如下查询：

• "使用查询 {duration>1s} 查询 Tempo 中的追踪"
• "使用查询 {service.name=\"frontend\"} 在 Tempo 中查找来自前端服务的追踪"
• "向我展示 Tempo 中最近的 50 个追踪，其中 {http.status_code=500}"

<img width="991" alt="Screenshot 2025-04-11 at 5 24 03 PM" src="https://github.com/user-attachments/assets/bcb1fb78-5532-48ab-ada2-4857f6f22514" />

许可证

本项目采用 MIT 许可证。