Alibabacloud Observability

---

📌 重要提示

本项目已使用 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

从源码构建

git clone https://github.com/aliyun/alibabacloud-observability-mcp-server.git
cd alibabacloud-observability-mcp-server
make build

配置

配置采用两层结构：

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

详细的配置项说明请参考 config.yaml 中的注释。

AI 工具集成

streamable-http 模式（推荐）

1. 配置 config.yaml（设置 server.transport: streamable-http）
2. 启动服务：./bin/alibabacloud-observability-mcp-server start
3. 配置 mcp.json：

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

stdio 模式

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

工具集

查看完整工具列表

运行以下命令查看当前注册的所有工具：

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

付费功能说明

以下 AI 智能工具每次调用会产生 STAROps 费用：

工具	功能
sls_text_to_sql	自然语言转 SQL
sls_text_to_spl	自然语言转 SPL
sls_sop	SLS 智能运维助手
cms_natural_language_query	自然语言数据查询

计费详情查看 STAROps 计费说明。如不需要 AI 能力，可在 config.yaml 的 enabled_tools 中仅启用免费工具。

权限要求

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

特殊权限：使用 AI 智能工具（如 sls_text_to_sql、cms_natural_language_query）需要授予 CMS 的 cms:CreateChat、cms:CreateThread 权限。

时间表达式

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

格式	示例
相对预设	last_5m、last_1h、last_1d
相对时间	now()-1h、now-30m
Grafana 风格	now-15m~now-5m、now/d、now-1d/d
绝对时间戳	1718451045（秒）、1718451045000（毫秒）
日期时间字符串	2024-01-01 00:00:00、2024-01-01T00:00:00Z

项目结构

├── cmd/server/          # CLI 入口
├── pkg/
│   ├── client/          # SLS/CMS 客户端
│   ├── config/          # 配置管理
│   ├── server/          # MCP Server 核心
│   └── toolkit/         # 工具集（PaaS/IaaS/Shared）
└── v1/                  # Python 版本

安全建议

• 服务不存储 AccessKey，仅在运行时用于 API 调用
• SSE/HTTP 模式下需自行做好访问控制
• 建议部署在内网或 VPC，避免暴露公网
• 推荐使用函数计算 (FC) 部署，仅 VPC 内访问

Skill 自动化部署

本项目提供 AI Agent Skill，支持通过自然语言指令完成部署、启动和更新。

安装 Skill

方式一：npx skills add（推荐）

由 Vercel Labs 维护的通用 skill 安装器，支持 69+ 种 coding agents：

# 全局安装（所有项目可用）
npx skills add aliyun/alibabacloud-observability-mcp-server

# 项目级安装（仅当前项目可用）
npx skills add aliyun/alibabacloud-observability-mcp-server --local

方式二：curl（无需 Node.js）

# 下载并安装 skill 到 ~/.claude/skills/
curl -fsSL https://raw.githubusercontent.com/aliyun/alibabacloud-observability-mcp-server/master/skills/deploy-observability/SKILL.md -o ~/.claude/skills/deploy-observability/SKILL.md

方式三：从项目仓库复制

如果你已经克隆了本项目：

# 全局安装
cp skills/deploy-observability/SKILL.md ~/.claude/skills/deploy-observability/

# 或项目级安装（在项目根目录下）
cp skills/deploy-observability/SKILL.md .claude/skills/deploy-observability/

使用 Skill

安装 skill 后，将以下内容复制到支持 Skill 的 AI Agent（如 Claude Code）中：

首次部署：

请使用 deploy-observability skill 帮我完成以下操作：
1. 克隆项目到 ~/alibabacloud-observability-mcp-server
2. 下载依赖并构建
3. 复制 .env.example 为 .env，并提示我填写阿里云 AccessKey
4. 让我选择启动模式（stdio / sse / streamable-http）
5. 生成 JSON 配置，供我粘贴到 AI Agent 中使用

项目更新：

请使用 deploy-observability skill 帮我更新项目：
1. 拉取最新代码
2. 检测是否有依赖、配置或环境变量变更
3. 对比工具列表变化，告诉我新增/删除了哪些工具
4. 重新构建并重启服务

详细使用文档请参考 skills/deploy-observability/SKILL.md。

许可证

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