Tempo MCP Server

已归档！

此项目已归档。Tempo 本身已内置 MCP 服务。请在 Tempo 仓库中提交问题和 PR。

Tempo MCP 服务

一个基于 Go 的服务实现，支持模型上下文协议（MCP）并集成 Grafana Tempo。

概览

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

开始使用

前提条件

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

构建和运行

构建并运行服务：

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

# Run the server
./tempo-mcp-server

或者直接使用 Go 运行：

go run ./cmd/server

该服务现在支持两种通信模式：

1. 遵循模型上下文协议（MCP）的标准输入/输出（stdin/stdout）
2. 带有服务器发送事件（SSE）端点的 HTTP 服务，可与 n8n 等工具集成

HTTP 服务的默认端口为 8080，但可通过 SSE_PORT 环境变量进行配置。

服务端点

在 HTTP 模式下运行时，服务会公开以下端点：

• SSE 端点：http://localhost:8080/sse - 用于实时事件流
• MCP 端点：http://localhost:8080/mcp - 用于 MCP 协议消息传递

Docker 支持

你可以使用 Docker 构建并运行 MCP 服务：

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

# Run the server
docker run -p 8080:8080 --rm -i tempo-mcp-server

或者，你可以使用 Docker Compose 创建完整的测试环境：

# Build and run with Docker Compose
docker-compose up --build

项目结构

.
├── cmd/
│   ├── server/       # MCP server implementation
│   └── client/       # Client for testing the MCP server
├── internal/
│   └── handlers/     # Tool handlers
├── pkg/
│   └── utils/        # Utility functions and shared code
└── go.mod            # Go module definition

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
• SSE_PORT：HTTP/SSE 服务的端口（默认值：8080）

测试

./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"]
    }
  }
}

与 n8n 配合使用

要在 n8n 中使用 Tempo MCP 服务，可以通过 MCP Client Tool 节点连接：

1. 将 MCP Client Tool 节点添加到 n8n 工作流

2. 使用以下参数配置节点：

   • SSE Endpoint：http://your-server-address:8080/sse（替换为实际的服务地址）
   • Authentication：如有需要，请选择适当的身份验证方式
   • Tools to Include：选择要向 AI Agent 开放的 Tempo 工具

3. 将 MCP Client Tool 节点连接到使用 Tempo 查询功能的 AI Agent 节点

示例工作流： 触发器 → MCP Client Tool（Tempo 服务）→ AI Agent（Claude）

使用示例

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

• “使用查询 {duration>1s} 在 Tempo 中查询 Trace”
• “使用查询 {service.name=\"frontend\"} 在 Tempo 中查找前端服务的 Trace”
• “在 Tempo 中显示最近的 50 条 Trace，查询条件为 {http.status_code=500}”

许可证

本项目采用 MIT 许可证。