Uptrace MCP Server

升级MCP服务器

模型上下文协议（MCP）服务器 上升记录 可观察性平台。提供通过Claude Desktop或其他MCP客户端查询跟踪、跨度和错误的工具。

特性

• 🔍 查询错误范围 -通过跟踪和堆栈跟踪获取详细的错误信息
• 📊 查询跨度 -使用Uptrace查询语言（UQL）进行筛选和搜索跨度
• 🔗 跟踪可视化 -获取包含所有相关跨度的完整跟踪树
• 📈 聚合 -按服务、运营等对跨度进行分组和汇总。
• 📝 查询日志 -按严重性、服务和自定义UQL查询搜索和过滤日志
• 📉 查询指标 -使用PromQL兼容语法查询指标
• 🏷️ 服务发现 -列出所有报告遥测数据的服务
• 📚 查询语法文档 -获取全面的UQL语法参考

安装

先决条件

• Python 3.10或更高版本
• 诗歌（推荐）或pip
• Uptrace实例（自托管或云）

使用紫外线（推荐）

uvx --from . uptrace-mcp

使用pip

pip install -e .

配置

创建一个 .env 在项目根目录中创建文件或设置环境变量：

UPTRACE_URL=https://uptrace.xxx
UPTRACE_PROJECT_ID=3
UPTRACE_API_TOKEN=your_token_here

您还可以通过传递以下命令来使用YAML文件进行配置 --config 参数。

# config.yaml
uptrace:
  api_url: "https://uptrace.example.com"
  project_id: "1"
  api_token: "your-api-token"
logging:
  level: debug
  file: "/path/to/uptrace-mcp.log"

这 logging 部分是可选的。默认情况下，服务器会记录标准错误(stderr)在 INFO 水平。

获取您的Uptrace API代币

1. 登录您的Uptrace实例
2. 转到您的用户配置文件
3. 导航到“身份验证令牌”部分
4. 创建具有读取权限的新令牌

备注：用户身份验证令牌不适用于单点登录（SSO）。如果使用SSO，请创建一个具有API访问权限的单独用户帐户。

用法

作为MCP服务器

光标IDE

📖 详细的设置指南：参见 CURSOR_SETUP.md 获取全面的指导。

要将此MCP服务器添加到游标，请执行以下操作：

1. 打开光标设置（在macOS上为Cmd+，在Windows/Linux上为Ctrl+）
2. 搜索“MCP”或导航到 特性 → 模型上下文协议
3. 点击 编辑配置 或直接打开MCP配置文件

配置文件位置：

• macOS: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• 视窗: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev\settings\cline_mcp_settings.json

快速设置：您可以使用示例配置文件 cursor-mcp-config.json.example 作为模板。将其复制到光标MCP设置文件，并更新路径和凭据。

重要：The cwd 参数指定执行命令的工作目录。这必须是您的根目录 uptrace-mcp 项目（其中 pyproject.toml 位于）。

添加以下配置（用实际项目路径替换路径）：

{
  "mcpServers": {
    "uptrace": {
      "command": "uvx",
      "args": ["--from", "/path/to/uptrace-mcp", "uptrace-mcp"],
      "env": {
        "UPTRACE_URL": "https://uptrace.xxx",
        "UPTRACE_PROJECT_ID": "3",
        "UPTRACE_API_TOKEN": "your_token_here"
      }
    }
  }
}

或者使用配置文件：

{
  "mcpServers": {
    "uptrace": {
      "command": "uvx",
      "args": ["--from", "/path/to/uptrace-mcp", "uptrace-mcp", "--config", "/path/to/config.yaml"]
    }
  }
}

配置参数：

• command -应该是 uvx
• args -传递给命令的参数(["--from", "project_path", "uptrace-mcp"])
• env -服务器的环境变量（如果使用 --config)

保存配置后，重新启动Cursor。Uptrace工具将在MCP工具面板中提供。

克劳德桌面版

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "uptrace": {
      "command": "uvx",
      "args": ["--from", "/Users/your-username/work/pet/uptrace-mcp", "uptrace-mcp"],
      "env": {
        "UPTRACE_URL": "https://uptrace.xxx",
        "UPTRACE_PROJECT_ID": "3",
        "UPTRACE_API_TOKEN": "your_token_here"
      }
    }
  }
}

重新启动Claude Desktop，Uptrace工具将可用。

直接运行

# Using uv
uv run uptrace-mcp

# Or if installed with pip
uptrace-mcp

# With config
uv run uptrace-mcp --config config.yaml

可用工具

跨度和痕迹

uptrace_search_spans

使用UQL使用自定义筛选器进行搜索跨度。使用 where _status_code = "error" 以查找错误跨度。

参数：

• time_gte （必填）：ISO格式的开始时间（YYYY-MM-DDTHH:MM:SSZ）
• time_lt （必填）：ISO格式的结束时间（YYYY-MM-DDTHH:MM:SSZ）
• query （可选）：UQL查询字符串
• limit （可选）：要返回的最大跨度（默认值：100）

示例：

Search spans where service_name = "aktar" and http_status_code = 404
from 2025-12-08T09:00:00Z to 2025-12-08T10:00:00Z

Find error spans: where _status_code = "error"
from 2025-12-08T09:00:00Z to 2025-12-08T10:00:00Z

uptrace_get_trace

获取特定跟踪ID的所有跨度。

参数：

• trace_id （必需）：要检索的跟踪ID

例子：

Get trace with ID 301015e15d95f1ea12af767ebf0ffcca

uptrace_search_groups

按组搜索和聚合跨度。

参数：

• time_gte （必填）：ISO格式的开始时间
• time_lt （必填）：ISO格式的结束时间
• query （必填）：带分组的UQL查询
• limit （可选）：返回的最大组数（默认值：100）

例子：

Group spans by service_name and count errors
from 2025-12-08T09:00:00Z to 2025-12-08T10:00:00Z
query: "where _status_code = 'error' | group by service_name | count()"

uptrace_search_services

搜索已报告跨度的服务。

参数：

• hours （可选）：回顾的小时数（默认值：24）

例子：

Search for all services from the last 48 hours

日志

uptrace_search_logs

按文本、严重性、服务名称或自定义UQL查询搜索日志。

参数：

• hours （可选）：回顾的小时数（默认值：3）
• search_text （可选）：在日志消息中搜索的文本（不区分大小写）
• severity （可选）：按日志严重性筛选（调试、信息、警告、错误、致命）
• service_name （可选）：按服务名称筛选
• query （可选）：用于高级筛选的附加UQL查询字符串
• limit （可选）：要返回的最大日志数（默认值：100）

示例：

Search logs containing "error" from the last 3 hours
Search ERROR level logs from service "aktar" in the last 6 hours

文档

uptrace_get_query_syntax

获取UQL（Uptrace查询语言）语法文档。返回用于查询跨度、日志和指标的运算符、函数、示例和常见模式。

参数：

• 无

例子：

Get UQL query syntax documentation

日志

客户端提供查询日志的方法（日志表示为span _system = "log:all"):

• query_logs() -按严重性、服务名称和自定义UQL查询使用过滤器查询日志
• get_error_logs() -获取错误日志（错误和致命严重级别）

示例用法：

from datetime import datetime, timedelta
from uptrace_mcp.client import UptraceClient

client = UptraceClient(
    base_url="https://uptrace.xxx",
    project_id="3",
    api_token="your_token"
)

# Get error logs from the last hour
time_lt = datetime.utcnow()
time_gte = time_lt - timedelta(hours=1)

logs = client.get_error_logs(time_gte=time_gte, time_lt=time_lt, limit=100)

# Query logs with custom filters
logs = client.query_logs(
    time_gte=time_gte,
    time_lt=time_lt,
    severity="ERROR",
    service_name="my-service",
    query='where log_message contains "database"',
    limit=50
)

指标

客户端提供了使用PromQL兼容语法查询指标的方法：

• query_metrics() -使用PromQL兼容格式查询指标
• query_metrics_groups() -按组查询和汇总指标

示例用法：

# Query metrics
result = client.query_metrics(
    time_gte=datetime.utcnow() - timedelta(hours=1),
    time_lt=datetime.utcnow(),
    metrics=["system_cpu_utilization as $cpu"],
    query=["avg($cpu) as cpu_avg"]
)

# Query metrics with grouping
result = client.query_metrics_groups(
    time_gte=datetime.utcnow() - timedelta(hours=1),
    time_lt=datetime.utcnow(),
    metrics=["uptrace_tracing_spans as $spans"],
    query=["sum($spans) as total_spans"],
    group_by=["service_name"]
)

附加跨度方法

客户端还提供了使用跨度的其他便利方法：

• get_span_by_id() -通过其ID获取特定跨度
• get_spans_by_parent() -按父跨度ID获取子跨度
• get_spans_by_system() -按系统类型（http、db、rpc等）筛选跨度
• get_slow_spans() -获取超过持续时间阈值的跨度
• get_query_syntax() -获取全面的UQL语法文档

例子：

# Get query syntax documentation
syntax = client.get_query_syntax()
print(syntax["operators"])
print(syntax["aggregation_functions"])
print(syntax["examples"])

UQL查询示例

Uptrace使用类似SQL的查询语言（UQL）。您可以使用以下命令获得全面的语法文档 client.get_query_syntax()以下是一些示例：

按状态筛选

where _status_code = "error"

按服务和时间筛选

where service_name = "aktar" and _dur_ms > 1000

HTTP错误

where _system = "httpserver" and http_status_code >= 400

分组和汇总

group by service_name | count() | avg(_dur_ms)

复杂查询

where _status_code = "error" and service_name in ("aktar", "gravipay")
| group by service_name, _name
| select service_name, _name, count(), p99(_dur_ms)

日志查询

where _system = "log:all" and log_severity in ("ERROR", "FATAL")
| group by service_name
| select service_name, count()

指标查询

metrics:
  - system_cpu_utilization as $cpu
query:
  - avg($cpu) as cpu_avg
  - sum($cpu) by (service_name) as cpu_by_service

Python客户端API

MCP服务器使用 UptraceClient 类内部。你也可以直接在Python代码中使用它：

from datetime import datetime, timedelta
from uptrace_mcp.client import UptraceClient

client = UptraceClient(
    base_url="https://uptrace.xxx",
    project_id="3",
    api_token="your_token"
)

# Query spans
spans = client.get_spans(
    time_gte=datetime.utcnow() - timedelta(hours=1),
    time_lt=datetime.utcnow(),
    query='where _status_code = "error"',
    limit=100
)

# Query logs
logs = client.query_logs(
    time_gte=datetime.utcnow() - timedelta(hours=1),
    time_lt=datetime.utcnow(),
    severity="ERROR",
    limit=50
)

# Query metrics
metrics = client.query_metrics(
    time_gte=datetime.utcnow() - timedelta(hours=1),
    time_lt=datetime.utcnow(),
    metrics=["uptrace_tracing_spans as $spans"],
    query=["sum($spans) as total"]
)

# Get query syntax documentation
syntax = client.get_query_syntax()

看 examples/query_errors.py 更多示例。

发展

运行测试

uv run pytest

代码格式化

uv run black src/
uv run ruff check src/

类型检查

uv run mypy src/

建筑

uptrace-mcp/
├── src/
│   └── uptrace_mcp/
│       ├── __init__.py
│       ├── server.py      # MCP server with tool handlers
│       ├── client.py      # Uptrace API client
│       └── models.py      # Pydantic data models
├── tests/                 # Test suite
├── pyproject.toml        # Poetry configuration
└── README.md

故障排除

在游标中找不到MCP服务器

如果在Cursor中看到“未找到服务器信息”错误：

1. 验证配置文件路径 -确保您正在编辑正确的MCP设置文件：

- macOS： ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json - 窗户： %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json - Linux： ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

1. 检查文件权限 -确保配置文件是有效的JSON并且可读

1. 验证uv/Python路径 -手动测试命令：

   cd /path/to/uptrace-mcp
   uv run uptrace-mcp --help

1. 检查环境变量 -确保在中设置了所有必需的变量 env 节，或a --config 指定了字符串：

- UPTRACE_URL - UPTRACE_PROJECT_ID - UPTRACE_API_TOKEN

1. 重新启动游标 -更改后，完全重新启动Cursor（而不仅仅是重新加载）

1. 检查游标日志 -在Cursor的开发人员控制台或日志中查找错误消息

连接问题

如果您遇到连接错误：

1. 验证 UPTRACE_URL 正确且包含协议（https://）
2. 检查一下 UPTRACE_PROJECT_ID 是一个有效的数字
3. 确保 UPTRACE_API_TOKEN 有效且未过期

权限错误

如果你收到403个禁止的错误：

• 验证令牌是否可以访问指定的项目
• 检查SSO是否已启用（需要单独的API用户帐户）

未返回数据

如果查询未返回任何数据：

• 检查时间范围是否正确（使用UTC时区）
• 通过Uptrace UI验证该时间段内是否存在跨度
• 先尝试不使用过滤器的更广泛的查询

手动测试服务器

1. 检查配置：

   cd /path/to/uptrace-mcp
   python check_config.py

1. 测试服务器启动：

   export UPTRACE_URL="https://uptrace.xxx"
   export UPTRACE_PROJECT_ID="3"
   export UPTRACE_API_TOKEN="your_token"
   uv run uptrace-mcp

服务器应无错误地启动。按Ctrl+C停止它。

1. 验证MCP协议：

服务器通过stdio进行通信，因此直接运行时看不到输出。 如果它启动时没有错误，那么它工作正常。

API文档

有关Uptrace API和UQL语法的更多信息，请参阅：

• Uptrace查询语言
• 上游API

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交拉取请求。