阿里云可观测 MCP Server（Go 版）

📌 重要提示

本项目已使用 Go 语言重构。如需使用原 Python 版本，请访问 v1 目录：

📖 v1/README.md - Python 版本文档

📦 Python 版本通过 pip install mcp-server-aliyun-observability 安装

阿里云可观测 MCP Server 的 Go 语言实现，为 AI 模型提供对阿里云日志服务（SLS）和云监控（CMS）的结构化数据访问能力。基于 Model Context Protocol 协议，可与 Cursor、Kiro、Cline、Windsurf 等 AI 工具无缝集成。

特性

支持 stdio、SSE、streamable-http 三种传输模式
模块化工具集架构：PaaS（云监控 2.0）、IaaS（SLS/CMS 直接访问）、Shared
灵活的时间表达式解析：相对时间、绝对时间戳、Grafana 风格、预设关键词
时序数据对比分析：统计计算、趋势分析、差异评分
结构化错误处理：英文错误描述和解决方案建议
稳定性保障：重试（指数退避）、熔断器、优雅关闭
结构化 JSON 日志（slog）
单一二进制文件，零运行时依赖

快速开始

下载与安装

从 Releases 页面下载对应平台的二进制文件：

# Linux amd64
wget https://github.com/aliyun/alibabacloud-observability-mcp-server/releases/latest/download/alibabacloud-observability-mcp-server-linux-amd64.tar.gz
tar -xzf alibabacloud-observability-mcp-server-linux-amd64.tar.gz

# macOS arm64 (M1/M2)
wget https://github.com/aliyun/alibabacloud-observability-mcp-server/releases/latest/download/alibabacloud-observability-mcp-server-darwin-arm64.tar.gz
tar -xzf alibabacloud-observability-mcp-server-darwin-arm64.tar.gz

解压后包含：

alibabacloud-observability-mcp-server - 可执行文件
config.yaml - 默认配置文件

配置凭证

# 设置阿里云 AccessKey
export ALIBABA_CLOUD_ACCESS_KEY_ID=<your_access_key_id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your_access_key_secret>

AccessKey 获取方式：阿里云 AccessKey 管理

启动服务

# 以 stdio 模式启动（MCP 客户端直接调用）
./alibabacloud-observability-mcp-server start --stdio

# 以网络模式启动（默认 transport 在 config.yaml 中配置）
./alibabacloud-observability-mcp-server start --config config.yaml

CLI 命令

# 查看版本信息
./alibabacloud-observability-mcp-server version

# 列出所有已注册工具
./alibabacloud-observability-mcp-server tools

从源码构建

前置条件

Go 1.23+

构建

# 克隆仓库
git clone https://github.com/aliyun/alibabacloud-observability-mcp-server.git
cd alibabacloud-observability-mcp-server

# 构建当前平台
make build

# 构建所有平台（linux/darwin/windows × amd64/arm64）
make build-all

生成的二进制文件位于 bin/ 目录。

配置

配置采用两层结构：

config.yaml - 服务器配置（传输模式、日志、网络等）
.env 文件或环境变量 - 凭证和运行时参数

配置文件

cp config.yaml config.yaml.bak       # 备份默认配置（可选）
cp .env.example .env                  # 凭证（AccessKey）

config.yaml 搜索路径：当前目录 → ./config/

.env 文件从当前目录加载，适合存放不宜提交到版本控制的凭证信息。

config.yaml 结构

# 服务器配置
server:
  transport: streamable-http  # stdio, sse, streamable-http
  host: "0.0.0.0"
  port: 8080

# 日志配置
logging:
  level: info                 # debug, info, warn, error
  debug_mode: false

# 工具集配置
toolkit:
  scope: all                  # all, paas, iaas
  # 精细化工具选择（可选，非空时仅注册列表中的工具）
  # enabled_tools:
  #   - list_workspace
  #   - umodel_get_entities
  #   - sls_execute_sql

# 网络配置
network:
  max_retry: 1
  retry_wait_seconds: 1
  read_timeout_ms: 610000
  connect_timeout_ms: 30000

# 本地化配置
locale:
  timezone: Asia/Shanghai
  language: zh-CN

# 运行时默认值（可选）
# 优先级: 环境变量 > .env 文件 > config.yaml
runtime:
  region: cn-hangzhou
  # workspace: ""

# 端点覆盖（可选，用于内网访问）
# endpoints:
#   sls:
#     cn-hongkong: "cn-hongkong-intranet.log.aliyuncs.com"
#   cms:
#     cn-hongkong: "cms.cn-hongkong.aliyuncs.com"

精细化工具选择

默认情况下，toolkit.scope 控制按类别启用工具（all/paas/iaas）。如果需要更细粒度的控制，可以使用 toolkit.enabled_tools 指定要启用的工具列表：

toolkit:
  scope: all
  enabled_tools:
    - list_workspace
    - list_domains
    - umodel_get_entities
    - umodel_get_metrics
    - sls_execute_sql

当 enabled_tools 非空时，只有列表中的工具会被注册，其余工具不可用。scope 仍然决定加载哪些 toolkit 模块，enabled_tools 在此基础上进一步过滤。

完整的工具列表及分类说明请参考 config.yaml 中的注释模板。

CLI 参数

参数	说明	默认值
`--config`	指定配置文件路径	自动搜索
`--stdio`	强制使用 stdio 传输模式	false

环境变量（凭证和运行时参数）

环境变量	说明	必需
`ALIBABA_CLOUD_ACCESS_KEY_ID`	AccessKey ID	否*
`ALIBABA_CLOUD_ACCESS_KEY_SECRET`	AccessKey Secret	否*
`ALIBABA_CLOUD_SECURITY_TOKEN`	STS Token（临时凭证）	否
`ALIBABA_CLOUD_REGION`	默认区域	否
`ALIBABA_CLOUD_WORKSPACE`	默认工作空间（PaaS 工具需要）	否

* 当未配置 AccessKey 时，服务会自动使用默认凭据链获取凭证（支持 ECS RAM Role、OIDC、配置文件等方式）。在 ECS、函数计算等云环境中无需手动配置 AccessKey。

凭证解析优先级：CLI 参数 / .env 文件 > shell 环境变量 > 默认凭据链。

💡 默认值自动填充

当设置了 ALIBABA_CLOUD_REGION 或 ALIBABA_CLOUD_WORKSPACE 时，如果工具调用中未提供 regionId 或 workspace 参数，服务会自动使用环境变量中的值作为默认值。用户显式传入的值不会被覆盖。

AI 工具集成

Cursor / Kiro / Cline

streamable-http 模式（推荐）：

配置 config.yaml（设置 server.transport: streamable-http）
启动服务：

./bin/alibabacloud-observability-mcp-server start

配置 mcp.json：

{
  "mcpServers": {
    "alibaba_cloud_observability": {
      "url": "http://localhost:8080"
    }
  }
}

stdio 模式：

配置 mcp.json：

{
  "mcpServers": {
    "alibaba_cloud_observability": {
      "command": "./bin/alibabacloud-observability-mcp-server",
      "args": ["start", "--stdio"],
      "env": {
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "<your_access_key_id>",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "<your_access_key_secret>"
      }
    }
  }
}

注意：stdio 模式下，如果 config.yaml 不存在，将使用内置默认值。

工具集

共 33 个工具，分为三个层级。

PaaS 工具集（云监控 2.0，推荐）

基于统一数据模型，工具名以 umodel_ 或 cms_ 为前缀。共 16 个工具。

实体管理工具

工具	说明	关键参数
`umodel_get_entities`	获取实体列表	`workspace`、`domain`、`entity_set_name`、`regionId`（必需）；`entity_filter`（可选）
`umodel_get_neighbor_entities`	获取实体邻居关系	`workspace`、`src_entity_domain`、`src_name`、`src_entity_ids`、`regionId`（必需）
`umodel_search_entities`	搜索实体	`workspace`、`search_text`、`regionId`（必需）

数据集管理工具

工具	说明	关键参数
`umodel_list_data_set`	列出数据集	`workspace`、`domain`、`entity_set_name`、`regionId`（必需）；`data_set_types`（可选）
`umodel_search_entity_set`	搜索实体集合	`workspace`、`search_text`、`regionId`（必需）
`umodel_get_entity_set`	获取实体集合 Schema 定义	`domain`、`entity_set_name`、`workspace`、`regionId`（必需）；`detail`（可选）
`umodel_list_related_entity_set`	列出关联实体集合	`workspace`、`domain`、`entity_set_name`、`regionId`（必需）

数据查询工具

工具	说明	关键参数
`umodel_get_metrics`	查询指标数据	`workspace`、`domain`、`entity_set_name`、`metric_domain_name`、`metric`、`regionId`（必需）；`analysis_mode`（basic/cluster/forecast/anomaly_detection）、`offset`（时序对比）、`time_range`（可选）
`umodel_get_golden_metrics`	查询黄金指标	`workspace`、`domain`、`entity_set_name`、`regionId`（必需）；`offset`、`time_range`（可选）
`umodel_get_relation_metrics`	查询关系指标	`workspace`、`src_domain`、`src_entity_set_name`、`relation_type`、`direction`（in/out）、`metric`、`metric_set_domain`、`regionId`（必需）；`dest_entity_set_name`（可选）
`umodel_get_logs`	查询日志数据	`workspace`、`domain`、`entity_set_name`、`log_set_domain`、`log_set_name`、`regionId`（必需）；`time_range`、`limit`（可选）
`umodel_get_events`	查询事件数据	`workspace`、`domain`、`entity_set_name`、`event_set_domain`、`event_set_name`、`regionId`（必需）；`time_range`、`limit`（可选）
`umodel_get_traces`	查询链路数据	`workspace`、`domain`、`entity_set_name`、`trace_set_domain`、`trace_set_name`、`trace_ids`、`regionId`（必需）；`time_range`（可选）
`umodel_search_traces`	搜索链路	`workspace`、`domain`、`entity_set_name`、`trace_set_domain`、`trace_set_name`、`regionId`（必需）；`conditions`、`limit`、`time_range`（可选）
`umodel_get_profiles`	查询性能剖析数据	`workspace`、`domain`、`entity_set_name`、`profile_set_domain`、`profile_set_name`、`entity_ids`、`regionId`（必需）；`time_range`、`limit`（可选）
`cms_natural_language_query`	自然语言数据查询	`query`、`workspace`、`regionId`（必需）；`time_range`（可选）

IaaS 工具集（SLS/CMS 直接访问）

直接访问底层 API，工具名以 sls_ 或 cms_ 为前缀。共 14 个工具。

SLS 工具

工具	说明	关键参数
`sls_list_projects`	列出项目	`regionId`（必需）；`project`（可选，模糊搜索）
`sls_list_logstores`	列出日志库	`project`、`regionId`（必需）
`sls_text_to_sql`	自然语言转 SQL	`text`、`project`、`logStore`、`regionId`（必需）
`sls_text_to_sql_old`	自然语言转 SQL（旧版，兼容 Python 版本）	`text`、`project`、`logStore`、`regionId`（必需）
`sls_text_to_spl`	自然语言转 SPL	`text`、`project`、`logStore`、`data_sample`、`regionId`（必需）
`sls_execute_sql`	执行 SQL 查询	`project`、`logStore`、`query`、`regionId`（必需）；`from_time`、`to_time`（可选）
`sls_execute_spl`	执行原生 SPL 查询	`query`、`workspace`、`regionId`（必需）；`from_time`、`to_time`（可选）
`sls_get_context_logs`	获取日志上下文	`project`、`logStore`、`pack_id`、`pack_meta`、`regionId`（必需）；`back_lines`、`forward_lines`（可选）
`sls_log_explore`	日志探索分析	`project`、`logStore`、`logField`、`regionId`（必需）；`from_time`、`to_time`、`filter_query`、`groupField`（可选）
`sls_log_compare`	日志对比分析	`project`、`logStore`、`logField`、`regionId`（必需）；`test_from_time`、`test_to_time`、`control_from_time`、`control_to_time`、`filter_query`、`groupField`（可选）
`sls_sop`	SLS 运维助手	`text`、`regionId`（必需）

CMS 工具

工具	说明	关键参数
`cms_execute_promql`	执行 PromQL 查询	`project`、`metricStore`、`query`、`regionId`（必需）；`from_time`、`to_time`（可选）
`cms_text_to_promql`	自然语言转 PromQL	`text`、`project`、`metricStore`、`regionId`（必需）

Shared 工具集

共 3 个工具。

工具	说明	关键参数
`list_workspace`	列出工作空间	`regionId`（必需）
`list_domains`	列出实体域	`workspace`、`regionId`（必需）
`introduction`	服务介绍	无参数

时间表达式

所有数据查询工具支持灵活的时间范围格式：

格式	示例
相对预设	`last_5m`、`last_1h`、`last_3d`、`last_1w`、`last_1M`、`last_1y`
相对时间	`now()-1h`、`now-30m`、`now()-7d`
Grafana 风格	`now-15m~now-5m`、`now/d`、`now-1d/d`
关键词	`today`、`yesterday`
绝对时间戳	`1718451045`（秒）、`1718451045000`（毫秒）
日期时间字符串	`2024-01-01 00:00:00`、`2024-01-01T00:00:00Z`

高级功能

时序对比分析

umodel_get_metrics 和 umodel_get_golden_metrics 支持通过 offset 参数进行时序对比：

# 对比当前1小时与1天前的数据
umodel_get_metrics(
    domain="apm", entity_set_name="apm.service",
    metric_domain_name="apm.metric.apm.service", metric="request_count",
    time_range="last_1h", offset="1d"
)

返回结果包含：

current: 当前时段统计（max, min, avg, count）
compare: 对比时段统计
diff: 变化分析（trend, avg_change, avg_change_percent）
diff_score: 差异评分（0-1，越大差异越显著）

高级分析模式

umodel_get_metrics 支持四种分析模式：

模式	说明	输出字段
`basic`	原始时序数据（默认）	`__ts__`, `__value__`, `__labels__`
`cluster`	K-Means时序聚类	`__cluster_index__`, `__entities__`, `__sample_value__`
`forecast`	时序预测（需1-5天历史数据）	`__forecast_ts__`, `__forecast_value__`, `__forecast_lower/upper_value__`
`anomaly_detection`	异常检测（需1-3天数据）	`__anomaly_list_`, `__anomaly_msg__`, `__value_min/max/avg__`

项目结构

├── cmd/server/          # CLI 入口（cobra）
├── pkg/
│   ├── client/          # SLS/CMS 客户端封装
│   ├── config/          # 配置管理（viper + sync.Once）
│   ├── endpoint/        # 端点解析
│   ├── errors/          # 结构化错误与错误码映射
│   ├── logger/          # 结构化日志（slog）
│   ├── server/          # MCP Server 核心（传输层、生命周期、健康检查）
│   ├── stability/       # 重试与熔断器
│   ├── timeparse/       # 时间表达式解析
│   └── toolkit/         # 工具集接口与注册中心
│       ├── paas/        # PaaS 工具集（umodel_*、cms_natural_language_query）
│       ├── iaas/        # IaaS 工具集（sls_*、cms_execute_promql、cms_text_to_promql）
│       └── shared/      # Shared 工具集（list_workspace、list_domains、introduction）
├── v1/                  # Python 版本（历史参考）
├── Makefile
├── go.mod
└── go.sum

开发

# 构建
make build

# 运行测试
make test

# 代码检查
make lint

# 清理构建产物
make clean

测试

项目采用单元测试 + 属性测试 + 回归测试三轨策略：

单元测试：表驱动测试，覆盖具体示例和边界条件
属性测试：使用 gopter，验证跨所有输入的通用正确性属性
回归测试：集成测试（//go:build integration），对比 Python 版本参数一致性，需要真实阿里云凭证

# 运行所有单元测试
go test ./... -v

# 仅运行属性测试
go test ./... -run TestProperty_

# 运行回归测试（需要配置环境变量）
ALIBABA_CLOUD_ACCESS_KEY_ID=xxx \
ALIBABA_CLOUD_ACCESS_KEY_SECRET=xxx \
ALIBABA_CLOUD_REGION=cn-hongkong \
ALIBABA_CLOUD_WORKSPACE=xxx \
go test -tags=integration ./pkg/toolkit/... -v

AI Agent 开发规范

参见 docs/AGENTS.md，包含项目结构说明、代码风格约定、新增工具流程、测试规范等。

权限要求

为了确保 MCP Server 能够成功访问和操作您的阿里云可观测性资源，您需要配置以下权限：

阿里云访问密钥 (AccessKey)

服务运行需要有效的阿里云凭证，支持以下方式（按优先级排列）：
1. AccessKey ID + AccessKey Secret（通过 .env 文件、环境变量或 CLI 参数传入）
2. STS 临时凭证（设置 ALIBABA_CLOUD_SECURITY_TOKEN 环境变量）
3. 默认凭据链自动发现（ECS RAM Role、OIDC、凭据配置文件等）
获取和管理 AccessKey，请参考阿里云 AccessKey 管理官方文档

RAM 授权

与 AccessKey 关联的 RAM 用户或角色必须被授予访问相关云服务所需的权限。

强烈建议遵循"最小权限原则"：仅授予运行您计划使用的 MCP 工具所必需的最小权限集。

根据您需要使用的工具，参考以下文档进行权限配置：

服务	权限文档	说明
日志服务 (SLS)	SLS 权限说明	`sls_*` 工具需要
应用实时监控 (ARMS)	ARMS 权限说明	`umodel_*` 工具需要
云监控 (CMS)	CMS 权限说明	`cms_*` 工具需要

特殊权限说明：

使用 SQL 生成类工具（如 sls_text_to_sql）需要单独授予 sls:CallAiTools 权限
使用自然语言查询功能（cms_natural_language_query）需要授予：cms:CreateChat、cms:CreateThread、cms:GetThread、cms:ListThreads

安全建议

服务不会存储 AccessKey，仅在运行时用于 API 调用
SSE/HTTP 模式下，务必自行做好接入点的访问控制
建议部署在内部网络或 VPC 内，避免直接暴露于公网
切勿在无认证的情况下将配置了 AccessKey 的服务端点暴露在公网
推荐使用阿里云函数计算 (FC) 部署，并配置为仅 VPC 内访问

许可证

本项目遵循与原 Python 版相同的许可协议。

Alibaba Cloud Observability