traceloop/opentelemetry-mcp-服务器
简介
核心亮点
- 打通 LLM 与 OpenTelemetry 生态的监控数据
- 支持 Grafana、Datadog 等主流观测平台
- 通过自然语言快速定位系统链路追踪问题
- 消除在监控面板与代码编辑器间的切换成本
完整文档
OpenTelemetry MCP Server
在 AI 辅助下查询和分析 LLM traces。 直接在 IDE 中要求 Claude 查找高成本的 API 调用、调试错误、对比模型性能或追踪 token 使用情况。
这是一个 MCP (Model Context Protocol) server，旨在将 AI 助手连接到 OpenTelemetry trace 后端（Jaeger, Tempo, Traceloop），并通过 OpenLLMetry 语义约定提供对 LLM 可观测性的专门支持。
演示视频：
https://github.com/user-attachments/assets/e2106ef9-0a58-4ba0-8b2b-e114c0b8b4b9
---
Table of Contents
---
Quick Start
无需安装！ 配置您的客户端直接从 PyPI 运行该 server：
// Add to claude_desktop_config.json:
{
"mcpServers": {
"opentelemetry-mcp": {
"command": "pipx",
"args": ["run", "opentelemetry-mcp"],
"env": {
"BACKEND_TYPE": "jaeger",
"BACKEND_URL": "http://localhost:16686"
}
}
}
}uvx（替代方案）：{
"mcpServers": {
"opentelemetry-mcp": {
"command": "uvx",
"args": ["opentelemetry-mcp"],
"env": {
"BACKEND_TYPE": "jaeger",
"BACKEND_URL": "http://localhost:16686"
}
}
}
}---
Installation
针对终端用户 (推荐)bash# Run without installing (recommended)
pipx run opentelemetry-mcp --backend jaeger --url http://localhost:16686
Or with uvx
uvx opentelemetry-mcp --backend jaeger --url http://localhost:16686
这种方法：
- ✅ 始终使用最新版本
- ✅ 无需全局安装
- ✅ 自动隔离环境
- ✅ 适用于所有平台
Per Client Integration
# Run without installing (recommended)
pipx run opentelemetry-mcp --backend jaeger --url http://localhost:16686
Or with uvx
uvx opentelemetry-mcp --backend jaeger --url http://localhost:16686<details>
<summary><b>Claude Desktop</b></summary>
在 Claude Desktop 配置文件中配置 MCP server：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
使用 pipx（推荐）：
{
"mcpServers": {
"opentelemetry-mcp": {
"command": "pipx",
"args": ["run", "opentelemetry-mcp"],
"env": {
"BACKEND_TYPE": "jaeger",
"BACKEND_URL": "http://localhost:16686"
}
}
}
}{
"mcpServers": {
"opentelemetry-mcp": {
"command": "uvx",
"args": ["opentelemetry-mcp"],
"env": {
"BACKEND_TYPE": "jaeger",
"BACKEND_URL": "http://localhost:16686"
}
}
}
}{
"mcpServers": {
"opentelemetry-mcp": {
"command": "pipx",
"args": ["run", "opentelemetry-mcp"],
"env": {
"BACKEND_TYPE": "traceloop",
"BACKEND_URL": "https://api.traceloop.com",
"BACKEND_API_KEY": "your_traceloop_api_key_here"
}
}
}
}<summary>使用仓库而非 pipx？</summary>
如果你正在使用克隆的仓库进行本地开发，请使用以下配置之一：
选项 1：Wrapper 脚本（便捷的后端切换）
{
"mcpServers": {
"opentelemetry-mcp": {
"command": "/absolute/path/to/opentelemetry-mcp-server/start_locally.sh"
}
}
}{
"mcpServers": {
"opentelemetry-mcp-jaeger": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/opentelemetry-mcp-server",
"run",
"opentelemetry-mcp"
],
"env": {
"BACKEND_TYPE": "jaeger",
"BACKEND_URL": "http://localhost:16686"
}
}
}
}</details>
<details>
<summary><b>Claude Code</b></summary>
Claude Code 与你在 Claude Desktop 配置中设置的 MCP servers 协同工作。完成上述配置后，你可以在 Claude Code CLI 中使用该 server：
# Verify the server is available
claude-code mcp list
Use Claude Code with access to your OpenTelemetry traces
claude-code "Show me traces with errors from the last hour"<details>
<summary><b>Codeium (Windsurf)</b></summary>
1. 打开 Windsurf
2. 导航至 Settings → MCP Servers
3. 点击 Add New MCP Server
4. 添加以下配置：
使用 pipx（推荐）：
{
"opentelemetry-mcp": {
"command": "pipx",
"args": ["run", "opentelemetry-mcp"],
"env": {
"BACKEND_TYPE": "jaeger",
"BACKEND_URL": "http://localhost:16686"
}
}
}{
"opentelemetry-mcp": {
"command": "uvx",
"args": ["opentelemetry-mcp"],
"env": {
"BACKEND_TYPE": "jaeger",
"BACKEND_URL": "http://localhost:16686"
}
}
}<summary>使用仓库版本？</summary>
{
"opentelemetry-mcp": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/opentelemetry-mcp-server",
"run",
"opentelemetry-mcp"
],
"env": {
"BACKEND_TYPE": "jaeger",
"BACKEND_URL": "http://localhost:16686"
}
}
}</details>
<details>
<summary><b>Cursor</b></summary>
1. 打开 Cursor
2. 导航至 Settings → MCP
3. 点击 Add new MCP Server
4. 添加以下配置：
使用 pipx（推荐）：
{
"opentelemetry-mcp": {
"command": "pipx",
"args": ["run", "opentelemetry-mcp"],
"env": {
"BACKEND_TYPE": "jaeger",
"BACKEND_URL": "http://localhost:16686"
}
}
}{
"opentelemetry-mcp": {
"command": "uvx",
"args": ["opentelemetry-mcp"],
"env": {
"BACKEND_TYPE": "jaeger",
"BACKEND_URL": "http://localhost:16686"
}
}
}<summary>使用 repository 而不是 pipx？</summary>
{
"opentelemetry-mcp": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/opentelemetry-mcp-server",
"run",
"opentelemetry-mcp"
],
"env": {
"BACKEND_TYPE": "jaeger",
"BACKEND_URL": "http://localhost:16686"
}
}
}</details>
<details>
<summary><b>Gemini CLI</b></summary>
在你的 Gemini CLI 配置文件 (~/.gemini/config.json) 中配置 MCP server：
使用 pipx（推荐）：
{
"mcpServers": {
"opentelemetry-mcp": {
"command": "pipx",
"args": ["run", "opentelemetry-mcp"],
"env": {
"BACKEND_TYPE": "jaeger",
"BACKEND_URL": "http://localhost:16686"
}
}
}
}{
"mcpServers": {
"opentelemetry-mcp": {
"command": "uvx",
"args": ["opentelemetry-mcp"],
"env": {
"BACKEND_TYPE": "jaeger",
"BACKEND_URL": "http://localhost:16686"
}
}
}
}gemini "Analyze token usage for gpt-4 requests today"<parameter name="name">改用 repository 吗？</summary>
{
"mcpServers": {
"opentelemetry-mcp": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/opentelemetry-mcp-server",
"run",
"opentelemetry-mcp"
],
"env": {
"BACKEND_TYPE": "jaeger",
"BACKEND_URL": "http://localhost:16686"
}
}
}
}</details>
_前置条件：_
- Python 3.11 或更高版本
<details>
<summary><b>可选：全局安装</b></summary>
如果您希望全局安装该命令：
# Install with pipx
pipx install opentelemetry-mcp
Verify
opentelemetry-mcp --help
Upgrade
pipx upgrade opentelemetry-mcppip install opentelemetry-mcp功能特性
核心能力
- 🔌 多后端支持 - 可连接至 Jaeger, Grafana Tempo 或 Traceloop
- 🤖 LLM 优先设计 - 专为分析 AI 应用 trace 设计的专业工具
- 🔍 高级过滤 - 具有强大操作符的通用过滤系统
- 📊 Token 分析 - 跨模型和服务追踪并汇总 LLM token 使用量
- ⚡ 高速且类型安全 - 基于 async Python 和 Pydantic 验证构建
工具| Tool | Description | Use Case |
| -------------------------- | ----------------------------------- | ---------------------------------- | |search_traces | 使用高级过滤器搜索 traces | 查找特定请求或模式 |
| search_spans | 搜索单个 spans | 分析特定操作 |
| get_trace | 获取完整的 trace 详情 | 深入分析单个 trace |
| get_llm_usage | 聚合 token 使用量指标 | 跟踪成本和使用趋势 |
| list_services | 列出可用服务 | 发现已接入监控的服务 |
| find_errors | 查找包含错误的 traces | 快速调试故障 |
| list_llm_models | 发现正在使用的模型 | 跟踪模型采用情况 |
| get_llm_model_stats | 获取模型性能统计数据 | 比较模型效率 |
| get_llm_expensive_traces | 查找 token 使用量最高的 traces | 优化成本 |
| get_llm_slow_traces | 查找最慢的操作 | 提升性能 |
Backend Support Matrix| 功能 | Jaeger | Tempo | Traceloop |
| ---------------- | :----: | :---: | :-------: | | 搜索 traces | ✓ | ✓ | ✓ | | 高级过滤器 | ✓ | ✓ | ✓ | | Span 搜索 | ✓\* | ✓ | ✓ | | Token 追踪 | ✓ | ✓ | ✓ | | 错误 traces | ✓ | ✓ | ✓ | | LLM 工具 | ✓ | ✓ | ✓ |<sub>\* Jaeger 的 span 搜索需要 service_name 参数</sub>
针对开发者
如果你在为该项目贡献代码或想要进行本地修改：
# Clone the repository
git clone https://github.com/traceloop/opentelemetry-mcp-server.git
cd opentelemetry-mcp-server
Install dependencies with UV
uv sync
Or install in development mode with editable install
uv pip install -e ".[dev]"Configuration
Supported Backends
| Backend | Type | URL Example | Notes |
| ------------- | ----------- | --------------------------- | -------------------------- |
| Jaeger | Local | http://localhost:16686 | 热门的开源选项 |
| Tempo | Local/Cloud | http://localhost:3200 | Grafana 的 trace 后端 |
| Traceloop | Cloud | https://api.traceloop.com | 需要 API key |
Quick Configuration
Option 1: Environment Variables (创建 .env 文件 - 参见 .env.example)
BACKEND_TYPE=jaeger
BACKEND_URL=http://localhost:16686opentelemetry-mcp --backend jaeger --url http://localhost:16686
opentelemetry-mcp --backend traceloop --url https://api.traceloop.com --api-key YOUR_KEY<details>
<summary><b>所有配置选项</b></summary>
| 变量 | 类型 | 默认值 | 描述 |
| ---------------------- | ------- | -------- | -------------------------------------------------- |
| BACKEND_TYPE | string | jaeger | Backend 类型：jaeger、tempo 或 traceloop |
| BACKEND_URL | URL | - | Backend API 端点（必填） |
| BACKEND_API_KEY | string | - | API key（Traceloop 必填） |
| BACKEND_TIMEOUT | integer | 30 | 请求超时时间（秒） |
| LOG_LEVEL | string | INFO | 日志级别：DEBUG、INFO、WARNING、ERROR |
| MAX_TRACES_PER_QUERY | integer | 100 | 每次查询返回的最大 trace 数量 (1-1000) |
完整的 .env 示例：
# Backend configuration
BACKEND_TYPE=jaeger
BACKEND_URL=http://localhost:16686
Optional: API key (mainly for Traceloop)
BACKEND_API_KEY=
Optional: Request timeout (default: 30s)
BACKEND_TIMEOUT=30
Optional: Logging level
LOG_LEVEL=INFO
Optional: Max traces per query (default: 100)
MAX_TRACES_PER_QUERY=100<details>
<summary><b>后端特定设置</b></summary>
JaegerbashBACKEND_TYPE=jaeger
BACKEND_URL=http://localhost:16686
### Grafana TempobashBACKEND_TYPE=tempo
BACKEND_URL=http://localhost:3200
### TraceloopbashBACKEND_TYPE=traceloop
BACKEND_URL=https://api.traceloop.com
BACKEND_API_KEY=your_api_key_here
> 注意： API key 包含项目信息。后端使用项目 slug "default"，而 Traceloop 会从 API key 中解析出实际的项目/环境。
BACKEND_TYPE=jaeger
BACKEND_URL=http://localhost:16686BACKEND_TYPE=tempo
BACKEND_URL=http://localhost:3200BACKEND_TYPE=traceloop
BACKEND_URL=https://api.traceloop.com
BACKEND_API_KEY=your_api_key_here</details>
---
使用方法
使用 start_locally.sh 快速启动（推荐）
运行服务器最简单的方法：
./start_locally.sh手动运行
对于高级用例或自定义配置，您可以手动运行服务器。
#### stdio 传输（用于 Claude Desktop）
使用 stdio 传输启动 MCP 服务器，以进行本地/Claude Desktop 集成：
# If installed with pipx/pip
opentelemetry-mcp
If running from cloned repository with UV
uv run opentelemetry-mcp
With backend override (pipx/pip)
opentelemetry-mcp --backend jaeger --url http://localhost:16686
With backend override (UV)
uv run opentelemetry-mcp --backend jaeger --url http://localhost:16686使用 HTTP/SSE transport 启动 MCP server 以实现远程访问：
# If installed with pipx/pip
opentelemetry-mcp --transport http
If running from cloned repository with UV
uv run opentelemetry-mcp --transport http
Specify custom host and port (pipx/pip)
opentelemetry-mcp --transport http --host 127.0.0.1 --port 9000
With UV
uv run opentelemetry-mcp --transport http --host 127.0.0.1 --port 9000http://localhost:8000/sse 访问 HTTP server。
传输方案使用场景：
- stdio transport：本地使用、Claude Desktop 集成、单进程
- HTTP transport：远程访问、多客户端、网络部署、示例应用
Tools 参考
1. search_traces
使用灵活的过滤条件搜索 traces：
{
"service_name": "my-app",
"start_time": "2024-01-01T00:00:00Z",
"end_time": "2024-01-01T23:59:59Z",
"gen_ai_system": "openai",
"gen_ai_model": "gpt-4",
"min_duration_ms": 1000,
"has_error": false,
"limit": 50
}service_name- 按服务过滤
operation_name- 按操作过滤
start_time/end_time- ISO 8601 时间戳
min_duration_ms/max_duration_ms- 耗时过滤器
gen_ai_system- LLM 提供商 (openai, anthropic 等)
gen_ai_model- 模型名称 (gpt-4, claude-3-opus 等)
has_error- 按错误状态过滤
tags- 自定义标签过滤器
limit- 最大结果数 (1-1000, 默认: 100)
返回值： 包含 token 计数的 trace 摘要列表
2. get_trace
获取完整的 trace 详情，包括所有 span 和 OpenLLMetry 属性：
{
"trace_id": "abc123def456"
}- 带有 attributes 的所有 spans
- LLM spans 的已解析 OpenLLMetry 数据
- 每个 span 的 token 使用量
- 错误信息
3. get_llm_usage
获取聚合的 token 使用量指标：
{
"start_time": "2024-01-01T00:00:00Z",
"end_time": "2024-01-01T23:59:59Z",
"service_name": "my-app",
"gen_ai_system": "openai",
"limit": 1000
}- Total prompt/completion/total tokens
- 按 model 分类统计
- 按 service 分类统计
- 请求次数
4. list_services
列出所有可用服务：
{}5. find_errors
查找包含错误的 trace：
{
"start_time": "2024-01-01T00:00:00Z",
"service_name": "my-app",
"limit": 50
}- 错误消息和类型
- 堆栈跟踪（已截断）
- LLM 特定错误信息
- Error span 详情
查询示例
查找高耗时 OpenAI 操作
自然语言： _"显示过去一小时内耗时超过 5 秒的 OpenAI traces"_
工具调用： search_traces
{
"service_name": "my-app",
"gen_ai_system": "openai",
"min_duration_ms": 5000,
"start_time": "2024-01-15T10:00:00Z",
"limit": 20
}{
"traces": [
{
"trace_id": "abc123...",
"service_name": "my-app",
"duration_ms": 8250,
"total_tokens": 4523,
"gen_ai_system": "openai",
"gen_ai_model": "gpt-4"
}
],
"count": 1
}按模型分析 Token 使用量
自然语言： _"今天每个模型使用了多少 token？"_
工具调用： get_llm_usage
{
"start_time": "2024-01-15T00:00:00Z",
"end_time": "2024-01-15T23:59:59Z",
"service_name": "my-app"
}{
"summary": {
"total_tokens": 125430,
"prompt_tokens": 82140,
"completion_tokens": 43290,
"request_count": 487
},
"by_model": {
"gpt-4": {
"total_tokens": 85200,
"request_count": 156
},
"gpt-3.5-turbo": {
"total_tokens": 40230,
"request_count": 331
}
}
}查找包含错误的 Trace
自然语言： _"显示过去一小时内的所有错误"_
工具调用： find_errors
{
"start_time": "2024-01-15T14:00:00Z",
"service_name": "my-app",
"limit": 10
}{
"errors": [
{
"trace_id": "def456...",
"service_name": "my-app",
"error_message": "RateLimitError: Too many requests",
"error_type": "openai.error.RateLimitError",
"timestamp": "2024-01-15T14:23:15Z"
}
],
"count": 1
}比较模型性能
自然语言： _"GPT-4 和 Claude 的性能差异是什么？"_
Tool Call 1： 针对 gpt-4 调用 get_llm_model_stats
{
"model_name": "gpt-4",
"start_time": "2024-01-15T00:00:00Z"
}get_llm_model_stats{
"model_name": "claude-3-opus-20240229",
"start_time": "2024-01-15T00:00:00Z"
}调查高 Token 消耗
自然语言： _"今天哪些请求使用了最多的 token？"_
工具调用： get_llm_expensive_traces
{
"limit": 10,
"start_time": "2024-01-15T00:00:00Z",
"min_tokens": 5000
}常见工作流
成本优化
1. 识别高成本操作：
Use get_llm_expensive_traces to find high-token requestsUse get_llm_usage to see which models are costing the mostUse get_trace with the trace_id to see exact prompts/responses1. 查找慢操作：
Use get_llm_slow_traces to identify latency issuesUse find_errors to see failure patternsUse get_llm_model_stats to see if responses are being truncated1. 发现正在使用的模型：
Use list_llm_models to see all models being calledUse get_llm_model_stats for each model to compare performanceLook for unexpected models or services in list_llm_models results开发
运行测试bash# With UV
uv run pytest
With coverage
uv run pytest --cov=openllmetry_mcp --cov-report=html
With pip
pytest
### 代码质量bash# Format code
uv run ruff format .
Lint
uv run ruff check .
Type checking
uv run mypy src/
## 故障排除
后端连接问题bash# Test backend connectivity
curl http://localhost:16686/api/services # Jaeger
curl http://localhost:3200/api/search/tags # Tempo
### 身份验证错误
# With UV
uv run pytest
With coverage
uv run pytest --cov=openllmetry_mcp --cov-report=html
With pip
pytest# Format code
uv run ruff format .
Lint
uv run ruff check .
Type checking
uv run mypy src/# Test backend connectivity
curl http://localhost:16686/api/services # Jaeger
curl http://localhost:3200/api/search/tags # Tempo请确保您的 API key 设置正确：
export BACKEND_API_KEY=your_key_here
Or use --api-key CLI flag
opentelemetry-mcp --api-key your_key_here- 检查时间范围（使用最近的时间戳）
- 使用
list_services验证服务名称
- 检查后端是否有 trace：
curl http://localhost:16686/api/services
- 尝试先在不使用过滤器的情况下进行搜索
Token 使用量显示为零
- 确保你的 trace 包含 OpenLLMetry instrumentation
- 检查 span 中是否存在
gen_ai.usage.*属性
- 使用
get_trace验证以查看原始 span 属性
未来增强
- [ ] 使用内置价格表进行成本计算
- [ ] 模型性能对比工具
- [ ] Prompt 模式分析
- [ ] 针对常用查询的 MCP resources
- [ ] 针对频繁查询的缓存层
- [ ] 支持更多后端（SigNoz, ClickHouse）
贡献
欢迎贡献！请确保：
1. 所有测试通过：pytest
2. 代码已格式化：ruff format .
3. 无 linting 错误：ruff check .
4. 类型检查通过：mypy src/
许可证
Apache 2.0 License - 详情请参阅 LICENSE 文件
相关项目
- OpenLLMetry - 针对 LLM 的 OpenTelemetry instrumentation
- Model Context Protocol - MCP 规范
- Claude Desktop - 支持 MCP 的 AI 助手
支持
问题与咨询：
- GitHub Issues: https://github.com/traceloop/opentelemetry-mcp-server/issues
- PyPI Package: https://pypi.org/project/opentelemetry-mcp/
- Traceloop Community: https://traceloop.com/slack
