# alibabacloud-observability-mcp-server **Repository Path**: mirrors_aliyun/alibabacloud-observability-mcp-server ## Basic Information - **Project Name**: alibabacloud-observability-mcp-server - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-04-22 - **Last Updated**: 2025-12-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README > 分支变动说明:`master` 已使用 `1.x.x` ;原 `master` 全量历史和代码已迁移到 `0.3.x` 分支,后续如需沿用旧版本,请在 `0.3.x` 上继续迭代。1.x 版本基于可观测 2.0 做了较大功能升级,工具形态与 0.3.x 有明显差异。详情见文末《0.3.x 与 1.x.x 工具差异对照》。后续我们将持续基于 1.x.x 版本维护和演进,感谢理解与支持。 ## 什么是 Observable MCP Server Observable MCP Server 是阿里云可观测官方推出的一个 MCP 服务,旨在为用户提供一整套的可观测 AI 交互能力,支持自然语言形式的多模态数据的访问和分析。可以与 Cursor、Cline、Windsurf 以及各类 Agent 框架无缝集成,使得企业人员可以更高效率和可靠地使用可观测数据。 ## MCP 是如何工作的 MCP(Model Context Protocol)为 AI 模型和开发环境之间建立统一的上下文交互标准,使模型可以在安全受控的前提下访问实时的领域知识。Observable MCP Server 通过这一协议,将自然语言需求映射为标准化工具调用,再透明地调度底层的日志、链路、指标等可观测产品接口,让智能体无需额外适配即可获取结构化结果。 Observable MCP Server 现已支持日志服务 SLS、应用实时监控服务 ARMS、云监控 CloudMonitor、Prometheus 监控等多款产品的查询与分析能力,并持续扩展更多可观测服务。 ## Observable MCP Server 的优势 1. 多源数据协同:一次接入即可同时查询 SLS、ARMS、CloudMonitor、Prometheus 等多款可观测产品的数据,统一呈现日志、指标与链路视角。 2. 自然语言驱动:无需手写查询语句,支持通过自然语言直接检索日志、链路、指标等信息,并返回结构化答案。 3. 企业级安全:基于阿里云 AccessKey 认证机制,服务端不额外采集数据,对每个工具的输入输出进行严格校验,保障数据安全可控。 ## 阿里云可观测MCP服务
### 简介
阿里云可观测 MCP服务,提供了一系列访问阿里云可观测各产品的工具能力,覆盖产品包含阿里云日志服务SLS、阿里云应用实时监控服务ARMS、阿里云云监控等,任意支持 MCP 协议的智能体助手都可快速接入。
### 工具架构
项目采用模块化架构,提供四个主要工具集:
- **PaaS工具集**(可观测2.0,推荐):包含 umodel 系列工具,提供统一数据模型的现代化可观测性能力
- `entity`: 实体发现和管理 (3个工具)
- `dataset`: 数据集和元数据管理 (3个工具)
- `data`: 各类数据查询,支持metrics、logs、events、traces、profiles (8个工具)
- **IaaS工具集**(V1兼容):传统SLS、CMS原生API工具,保持向后兼容 (7个工具)
- **Shared工具集**:跨服务共享工具,如workspace和domain管理 (3个工具)
📚 **详细的工具组合推荐请参考**:[最佳工具组合推荐文档](./docs/best_practices_toolkit_combinations.md)
### 版本记录
可以查看 [CHANGELOG.md](./CHANGELOG.md)
### 常见问题
可以查看 [FAQ.md](./FAQ.md)
### 工具列表
#### PaaS工具集(可观测2.0)
##### 实体管理工具 (entity)
| 工具名称 | 用途 | 关键参数 | 最佳实践 |
|---------|------|---------|---------|
| `umodel_get_entities` | 获取指定实体集的实体列表 | `workspace`:工作空间名称(必需)
`domain`:实体域(必需)
`entity_set_name`:实体类型(必需)
`regionId`:阿里云区域ID(必需) | - 用于探索可用的实体资源
- 支持精确查询指定实体 |
| `umodel_get_neighbor_entities` | 获取实体的邻居节点 | `workspace`:工作空间名称(必需)
`domain`:实体域(必需)
`entity_set_name`:实体类型(必需)
`entity_ids`:实体ID列表(必需)
`regionId`:阿里云区域ID(必需) | - 探索服务依赖关系
- 构建拓扑图 |
| `umodel_search_entities` | 搜索匹配条件的实体 | `workspace`:工作空间名称(必需)
`domain`:实体域(必需)
`entity_set_name`:实体类型(必需)
`search_conditions`:搜索条件
`regionId`:阿里云区域ID(必需) | - 支持复杂查询条件
- 灵活实体发现 |
##### 数据集管理工具 (dataset)
| 工具名称 | 用途 | 关键参数 | 最佳实践 |
|---------|------|---------|---------|
| `umodel_list_data_set` | 列出指定类型的数据集 | `workspace`:工作空间名称(必需)
`domain`:实体域(必需)
`entity_set_name`:实体类型(必需)
`data_set_types`:数据集类型(可选)
`regionId`:阿里云区域ID(必需) | - 发现可用的数据集
- 了解数据结构和字段 |
| `umodel_search_entity_set` | 搜索实体集 | `workspace`:工作空间名称(必需)
`search_text`:搜索关键词(必需)
`regionId`:阿里云区域ID(必需) | - 通过关键词发现实体集
- 支持模糊搜索 |
| `umodel_list_related_entity_set` | 列出相关联的实体集 | `workspace`:工作空间名称(必需)
`domain`:实体域(必需)
`entity_set_name`:实体类型(必需)
`regionId`:阿里云区域ID(必需) | - 了解实体集间的关联关系
- 探索数据依赖 |
##### 数据查询工具 (data)
| 工具名称 | 用途 | 关键参数 | 最佳实践 |
|---------|------|---------|---------|
| `umodel_get_metrics` | 获取实体的时序指标数据,支持高级分析模式 | `workspace`:工作空间名称(必需)
`domain`:实体域(必需)
`entity_set_name`:实体类型(必需)
`metric_domain_name`:指标域名称(必需)
`metric`:指标名称(必需)
`analysis_mode`:分析模式(可选,默认basic)
`forecast_duration`:预测时长(可选)
`regionId`:阿里云区域ID(必需) | - 支持range/instant查询
- **basic**: 原始时序数据
- **cluster**: K-Means聚类分析
- **forecast**: 时序预测(1-5天学习)
- **anomaly_detection**: 异常检测(1-3天学习) |
| `umodel_get_golden_metrics` | 获取黄金指标数据 | `workspace`:工作空间名称(必需)
`domain`:实体域(必需)
`entity_set_name`:实体类型(必需)
`regionId`:阿里云区域ID(必需) | - 快速获取关键性能指标
- 包含延迟、吞吐量、错误率等 |
| `umodel_get_relation_metrics` | 获取实体间关系级别的指标 | `workspace`:工作空间名称(必需)
`src_domain`:源实体域(必需)
`src_entity_set_name`:源实体类型(必需)
`src_entity_ids`:源实体ID列表(必需)
`relation_type`:关系类型(必需)
`direction`:关系方向(必需)
`regionId`:阿里云区域ID(必需) | - 分析微服务调用关系
- 支持服务依赖分析 |
| `umodel_get_logs` | 获取实体相关的日志数据 | `workspace`:工作空间名称(必需)
`domain`:实体域(必需)
`entity_set_name`:实体类型(必需)
`log_set_name`:日志集名称(必需)
`log_set_domain`:日志集域(必需)
`regionId`:阿里云区域ID(必需) | - 用于故障诊断
- 支持性能分析 |
| `umodel_get_events` | 获取实体的事件数据 | `workspace`:工作空间名称(必需)
`domain`:实体域(必需)
`entity_set_name`:实体类型(必需)
`event_set_domain`:事件集域(必需)
`event_set_name`:事件集名称(必需)
`regionId`:阿里云区域ID(必需) | - 用于异常事件分析
- 支持告警事件追踪 |
| `umodel_get_traces` | 获取指定trace ID的详细数据,包含独占耗时 | `workspace`:工作空间名称(必需)
`domain`:实体域(必需)
`entity_set_name`:实体类型(必需)
`trace_set_domain`:链路集域(必需)
`trace_set_name`:链路集名称(必需)
`trace_ids`:链路ID列表(必需)
`regionId`:阿里云区域ID(必需) | - 深入分析调用链
- 包含 `exclusive_duration_ms` 独占耗时
- 按独占耗时排序定位瓶颈 |
| `umodel_search_traces` | 基于条件搜索调用链 | `workspace`:工作空间名称(必需)
`domain`:实体域(必需)
`entity_set_name`:实体类型(必需)
`trace_set_domain`:链路集域(必需)
`trace_set_name`:链路集名称(必需)
`regionId`:阿里云区域ID(必需) | - 支持按持续时间、错误状态过滤
- 返回链路摘要信息 |
| `umodel_get_profiles` | 获取性能剖析数据 | `workspace`:工作空间名称(必需)
`domain`:实体域(必需)
`entity_set_name`:实体类型(必需)
`profile_set_domain`:性能剖析集域(必需)
`profile_set_name`:性能剖析集名称(必需)
`entity_ids`:实体ID列表(必需)
`regionId`:阿里云区域ID(必需) | - 用于性能瓶颈分析
- 包含CPU、内存使用情况 |
#### Shared工具集(共享工具)
##### 工作空间和域管理
| 工具名称 | 用途 | 关键参数 | 最佳实践 |
|---------|------|---------|---------|
| `introduction` | 获取服务介绍和使用说明 | 无需参数 | - 首次接入时了解服务能力
- 作为 LLM Agent 的自我介绍工具 |
| `list_workspace` | 获取可用工作空间列表 | `regionId`:阿里云区域ID(必需) | - 在使用其他工具前先获取工作空间
- 支持跨区域工作空间查询 |
| `list_domains` | 获取工作空间中的所有实体域 | `workspace`:工作空间名称(必需)
`regionId`:阿里云区域ID(必需) | - 在查询实体前先了解可用的域
- 了解数据分类情况 |
#### IaaS工具集(V1兼容)
##### SLS和CMS原生API工具
| 工具名称 | 用途 | 关键参数 | 最佳实践 |
|---------|------|---------|---------|
| `cms_text_to_promql` | 将自然语言转换为PromQL查询 | `text`:自然语言问题(必需)
`project`:项目名称(必需)
`metricStore`:指标存储名称(必需)
`regionId`:阿里云区域ID(必需) | - 智能生成PromQL语句
- 简化查询操作 |
| `sls_text_to_sql` | 将自然语言转换为SQL查询 | `text`:自然语言问题(必需)
`project`:SLS项目名称(必需)
`logStore`:日志存储名称(必需)
`regionId`:阿里云区域ID(必需) | - 智能生成SLS SQL查询
- 支持自然语言交互 |
| `sls_execute_sql` | 执行SLS SQL查询 | `project`:SLS项目名称(必需)
`logStore`:日志存储名称(必需)
`query`:SQL查询语句(必需)
`from_time`:查询开始时间(必需)
`to_time`:查询结束时间(必需)
`regionId`:阿里云区域ID(必需) | - 直接执行SQL查询
- 使用适当时间范围优化性能 |
| `cms_execute_promql` | 执行PromQL查询 | `project`:项目名称(必需)
`metricStore`:指标存储名称(必需)
`query`:PromQL查询语句(必需)
`start_time`:查询开始时间(必需)
`end_time`:查询结束时间(必需)
`regionId`:阿里云区域ID(必需) | - 查询云监控指标数据
- 支持标准PromQL语法 |
| `sls_list_projects` | 列出SLS项目 | `projectName`:项目名称(可选,模糊搜索)
`regionId`:阿里云区域ID(必需) | - 发现可用的SLS项目
- 支持模糊搜索 |
| `sls_execute_spl` | 执行原生SPL查询 | `query`:SPL查询语句(必需)
`regionId`:阿里云区域ID(必需) | - 执行复杂的SLS查询
- 支持高级分析功能 |
| `sls_list_logstores` | 列出指定项目的日志存储 | `project`:SLS项目名称(必需)
`regionId`:阿里云区域ID(必需) | - 发现项目中的日志存储
- 了解数据分布 |
### 权限要求
为了确保 MCP Server 能够成功访问和操作您的阿里云可观测性资源,您需要配置以下权限:
1. **阿里云访问密钥 (AccessKey)**:
* 服务运行需要有效的阿里云 AccessKey ID 和 AccessKey Secret。
* 获取和管理 AccessKey,请参考 [阿里云 AccessKey 管理官方文档](https://help.aliyun.com/document_detail/53045.html)。
2. 当你初始化时候不传入 AccessKey 和 AccessKey Secret 时,会使用[默认凭据链进行登录](https://www.alibabacloud.com/help/zh/sdk/developer-reference/v2-manage-python-access-credentials#62bf90d04dztq)
1. 如果环境变量 中的ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET均存在且非空,则使用它们作为默认凭据。
2. 如果同时设置了ALIBABA_CLOUD_ACCESS_KEY_ID、ALIBABA_CLOUD_ACCESS_KEY_SECRET和ALIBABA_CLOUD_SECURITY_TOKEN,则使用STS Token作为默认凭据。
3. **RAM 授权 (重要)**:
* 与 AccessKey 关联的 RAM 用户或角色**必须**被授予访问相关云服务所需的权限。
* **强烈建议遵循"最小权限原则"**:仅授予运行您计划使用的 MCP 工具所必需的最小权限集,以降低安全风险。
* 根据您需要使用的工具,参考以下文档进行权限配置:
* **日志服务 (SLS)**:如果您需要使用 `sls_*` 相关工具,请参考 [日志服务权限说明](https://help.aliyun.com/zh/sls/overview-8),并授予必要的读取、查询等权限。
* **应用实时监控服务 (ARMS)**:如果您需要使用 `arms_*` 相关工具,请参考 [ARMS 权限说明](https://help.aliyun.com/zh/arms/security-and-compliance/overview-8?scm=20140722.H_74783._.OR_help-T_cn~zh-V_1),并授予必要的查询权限。
* 特殊权限说明,如果使用了SQL生成之类的工具,需要单独授予`sls:CallAiTools`的权限
* 请根据您的实际应用场景,精细化配置所需权限。
### 安全与部署建议
请务必关注以下安全事项和部署最佳实践:
1. **密钥安全**:
* 本 MCP Server 在运行时会使用您提供的 AccessKey 调用阿里云 OpenAPI,但**不会以任何形式存储您的 AccessKey**,也不会将其用于设计功能之外的任何其他用途。
2. **访问控制 (关键)**:
* 当您选择通过 **SSE (Server-Sent Events) 协议** 访问 MCP Server 时,**您必须自行负责该服务接入点的访问控制和安全防护**。
* **强烈建议**将 MCP Server 部署在**内部网络或受信环境**中,例如您的私有 VPC (Virtual Private Cloud) 内,避免直接暴露于公共互联网。
* 推荐的部署方式是使用**阿里云函数计算 (FC)**,并配置其网络设置为**仅 VPC 内访问**,以实现网络层面的隔离和安全。
* **注意**:**切勿**在没有任何身份验证或访问控制机制的情况下,将配置了您 AccessKey 的 MCP Server SSE 端点暴露在公共互联网上,这会带来极高的安全风险。
### 使用说明
在使用 MCP Server 之前,需要先获取阿里云的 AccessKeyId 和 AccessKeySecret,请参考 [阿里云 AccessKey 管理](https://help.aliyun.com/document_detail/53045.html)
#### 使用 pip 安装
> ⚠️ 需要 Python 3.10 及以上版本。
直接使用 pip 安装即可,安装命令如下:
```bash
# 安装(包含所有功能和依赖)
pip install mcp-server-aliyun-observability
```
1. 安装之后,直接运行即可,运行命令如下:
```bash
# 默认使用streamableHttp方式启动
python -m mcp_server_aliyun_observability
# 指定访问密钥启动
python -m mcp_server_aliyun_observability --access-key-id
- 性能优异
- 生产级稳定性 | - 需要网络配置 |
| **stdio** | 本地开发、命令行工具 | - 最简单的集成方式
- 无网络配置要求
- 直接进程间通信 | - 仅限本地使用
- 无法多客户端同时访问 |
| **sse** (Server-Sent Events) | Web应用、远程访问 | - 支持远程连接
- 基于标准HTTP协议
- 支持多客户端 | - 需要维护长连接
- 性能较streamableHttp略低 |
> 💡 **推荐使用**: 生产环境和Web应用使用 `streamableHttp`(默认),本地开发使用 `stdio`,特殊场景使用 `sse`
### AI 工具集成
#### Cursor,Cline 等集成
**推荐方式:使用 streamableHttp(默认)**
```bash
python -m mcp_server_aliyun_observability
```
```json
{
"mcpServers": {
"alibaba_cloud_observability": {
"url": "http://localhost:8000"
}
}
}
```
**使用 uvx 启动方式**
```json
{
"mcpServers": {
"alibaba_cloud_observability": {
"command": "uvx",
"args": [
"mcp-server-aliyun-observability"
],
"env": {
"ALIBABA_CLOUD_ACCESS_KEY_ID": "