Cubeapm MCP

CubeAPM MCP服务器

A. 模型上下文协议（MCP） 服务器 CubeAPM -使像Claude这样的人工智能助手能够查询您的可观察性数据，包括跟踪、指标和日志。

这是什么？

此MCP服务器将AI助手（如Claude）连接到您的CubeAPM实例，允许您：

• 查询日志 使用翻译成LogsQL的自然语言
• 分析指标 与PromQL兼容的查询
• 搜索和检查痕迹 调试分布式系统
• 监控您的服务 通过对话式界面

安装

来自NPM（推荐）

npm install -g cubeapm-mcp

源自源头

git clone https://github.com/TechnicalRhino/cubeapm-mcp.git
cd cubeapm-mcp
npm install
npm run build

快速开始

1.配置克劳德代码

添加到您的克劳德代码设置(~/.claude/settings.json):

{
  "mcpServers": {
    "cubeapm": {
      "command": "npx",
      "args": ["-y", "cubeapm-mcp"],
      "env": {
        "CUBEAPM_HOST": "your-cubeapm-server.com"
      }
    }
  }
}

2.重新启动克劳德代码

更新设置后，重新启动Claude Code以加载MCP服务器。

3.开始查询

现在，您可以向Claude提出以下问题：

• *“显示最近一小时支付服务的错误日志”*
• *“签出API的p99延迟是多少？”*
• *“查找生产中持续时间>5s的痕迹”*
• *“获取跟踪ID abc123def456的完整跟踪”*

配置

示例配置

地方发展：

{
  "mcpServers": {
    "cubeapm": {
      "command": "npx",
      "args": ["-y", "cubeapm-mcp"],
      "env": {
        "CUBEAPM_HOST": "localhost"
      }
    }
  }
}

生产（带完整URL）：

{
  "mcpServers": {
    "cubeapm": {
      "command": "npx",
      "args": ["-y", "cubeapm-mcp"],
      "env": {
        "CUBEAPM_URL": "https://cubeapm.internal.company.com"
      }
    }
  }
}

生产（带主机/端口）：

{
  "mcpServers": {
    "cubeapm": {
      "command": "npx",
      "args": ["-y", "cubeapm-mcp"],
      "env": {
        "CUBEAPM_HOST": "cubeapm.internal.company.com",
        "CUBEAPM_QUERY_PORT": "3140"
      }
    }
  }
}

可用工具

日志

参数：

• query -LogsQL查询字符串（例如。， {service="api"} error)
• start -开始时间（RFC3339或Unix时间戳）
• end -结束时间（RFC3339或Unix时间戳）
• limit -返回的最大条目数（默认值：100）

指标

即时查询参数：

• query -PromQL表达式
• time -评估时间戳
• step -可选时间窗口（秒）

范围查询参数：

• query -PromQL表达式
• start / end -时间范围
• step -分辨率（秒）

痕迹

搜索参数（必填）：

• query -搜索查询（默认值： * 对于通配符）
• env -环境过滤器（默认值： UNSET)
• service -服务名称筛选器(必需的，区分大小写）
• start / end -时间范围（RFC3339或Unix时间戳）

搜索参数（可选）：

• limit -最大结果（默认值：20）
• spanKind -按跨度类型筛选： server, client, consumer, producer
• sortBy -排序方式： duration （可用于查找慢速痕迹）

获取跟踪参数：

• trace_id -十六进制编码的跟踪ID
• start / end -搜索时间范围

摄入

提示

常见可观察性任务的预定义模板：

使用示例：

Use the investigate-service prompt for Kratos-Prod

资源

公开CubeAPM数据和配置的可读资源：

CubeAPM查询模式

度量（PromQL/MetricsQL）

CubeAPM使用与标准OpenTetry不同的特定命名约定：

直方图查询（P50、P90、P95、P99）

CubeAPM使用 VictoriaMetrics风格直方图 随着 vmrange 标签而不是普罗米修斯 le 水桶：

# ✅ Correct - Use histogram_quantiles() with vmrange
histogram_quantiles("phi", 0.95, sum by (vmrange, service) (
  increase(cube_apm_latency_bucket{service="MyService", span_kind="server"}[5m])
))

# ❌ Wrong - Standard Prometheus syntax won't work
histogram_quantile(0.95, sum by (le) (rate(http_request_duration_bucket[5m])))

注： 延迟值在中返回 秒 （0.05=50ms）

日志（LogsQL）

流选择器

日志标签因来源而异。使用 * 首先查询以发现可用标签：

# Discover all labels
*

# Lambda function logs
{faas.name="my-lambda-prod"}

# Regex match
{faas.name=~".*-prod"}

# Text filter with boolean operators
{faas.name=~".*"} AND "error" AND NOT "retry"

管道操作员

任何查询后的链 |:

统计功能

与 | stats 管道：

日志查询示例

# Count errors per Lambda function
{faas.name=~".*"} AND "error" | stats count() as errors by (faas.name)

# Top 10 slowest requests
{service_name="my-service"} | sort by (duration) desc | limit 10

# Extract and aggregate from JSON logs
{service_name="api"} | unpack_json | stats avg(response_time) as avg_rt by (endpoint)

痕迹

跟踪查询使用与日志相同的管道语法： {stream_selector} | pipe1 | pipe2

重要提示：

• query, env, service 是必需的参数
• 持续时间为 毫秒 （不是像指标那样的秒数）
• p95 不是有效的统计函数--使用 quantile(0.95, duration)
• 服务名称区分大小写（例如。， "Kratos-Prod" 不 "kratos")

跟踪查询示例

# P95 latency for a service
{service="Kratos-Prod", span_kind="server"} | stats quantile(0.95, duration) as p95_ms

# Error count by endpoint
{service="Kratos-Prod", status_code="ERROR"} | stats count() as errors by (http_route)

# Slowest spans
{service="Kratos-Prod"} | sort by (duration) desc | limit 20

自然语言查询示例

日志

"Show me logs from webhook-lambda-prod"
"Find all logs containing 'timeout' in the last hour"
"Count errors per Lambda function in the last 24h"

指标

"What's the P95 latency for Kratos-Prod service?"
"Show me error rate for all services"
"List all available services in CubeAPM"

痕迹

"Find the P95 latency for Kratos-Prod using trace stats"
"Show me traces with errors in the production environment"
"Get the full waterfall for trace ID abc123"

发展

# Clone the repository
git clone https://github.com/TechnicalRhino/cubeapm-mcp.git
cd cubeapm-mcp

# Install dependencies
npm install

# Run in development mode (with hot reload)
npm run dev

# Build for production
npm run build

# Test the build
npm start

运作原理

┌─────────────────┐     MCP Protocol     ┌─────────────────┐     HTTP API     ┌─────────────────┐
│  Claude / AI    │◄───────────────────►│  cubeapm-mcp    │◄────────────────►│    CubeAPM      │
│   Assistant     │   (stdio transport)  │   MCP Server    │   (REST calls)   │    Server       │
└─────────────────┘                      └─────────────────┘                  └─────────────────┘

MCP服务器：

1. 通过stdio接收来自AI助手的工具调用
2. 将它们转换为CubeAPM HTTP API请求
3. 将格式化的结果返回给助手

需求

• Node.js 18+
• CubeAPM 实例（自托管或云）
• 克劳德代码 或任何MCP兼容客户端

相关链接

• CubeAPM文档
• CubeAPM HTTP API
• 模型上下文协议
• 克劳德代码

贡献

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

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。