Tempo MCP Server (Scottlepp)

存档！

Tempo MCP服务器

基于Go语言的模型上下文协议（MCP）服务器实现，集成了Grafana Tempo。

概述

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

入门指南

先决条件

• 达到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：用于身份验证的承载令牌（可选）

环境变量

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桌面配置示例：

{
  "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

与光标一起使用

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

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

与n8n一起使用

要将Tempo MCP服务器与n8n一起使用，您可以使用MCP客户端工具节点连接到它：

1. 添加一个 MCP客户端工具 节点到n8n工作流

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

- SSE端点: http://your-server-address:8080/sse （替换为您的实际服务器地址） - 认证：如果需要，请选择适当的身份验证 - 要包含的工具：选择要向AI Agent公开的Tempo工具

1. 将MCP客户端工具节点连接到将使用Tempo查询功能的AI代理节点

工作流程示例： 触发→ MCP客户端工具（Tempo服务器）→ 人工智能代理（克劳德）

示例用法

配置后，您可以使用Claude中的工具进行以下查询：

• “使用查询在Tempo中查询跟踪信息 {duration>1s}"
• “使用查询从Tempo中的前端服务查找痕迹 {service.name=\"frontend\"}"
• “给我看看Tempo最近的50条痕迹 {http.status_code=500}"

许可证

该项目根据MIT许可证获得许可。