mcp-server-aliyun-observability 1.0.0a1

aliyun observability mcp server

阿里云可观测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个工具)
• DoraAI工具集：AI智能洞察分析工具 (1个工具)
• Shared工具集：跨服务共享工具，如workspace和domain管理 (2个工具)

通过环境变量 MCP_ENABLED_TOOLKITS 或 --toolkits 参数可以灵活控制启用哪些工具包：

• 启用PaaS工具集（推荐）：MCP_ENABLED_TOOLKITS=paas 或 --toolkits paas
• 启用传统IaaS工具：MCP_ENABLED_TOOLKITS=iaas 或 --toolkits iaas
• 启用AI洞察工具：MCP_ENABLED_TOOLKITS=doraai 或 --toolkits doraai
• 启用共享工具：MCP_ENABLED_TOOLKITS=shared 或 --toolkits shared
• 启用所有工具（默认）：MCP_ENABLED_TOOLKITS=all 或 --toolkits all

📚 详细的工具组合推荐请参考：最佳工具组合推荐文档

版本记录

可以查看 CHANGELOG.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：指标名称（必需） regionId：阿里云区域ID（必需）	- 支持range/instant查询 - 可指定时间范围和聚合方式
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（必需）	- 深入分析调用链 - 包含完整span信息
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工具集（共享工具）

工作空间和域管理

工具名称	用途	关键参数	最佳实践
list_workspace	获取可用工作空间列表	regionId：阿里云区域ID（必需）	- 在使用其他工具前先获取工作空间 - 支持跨区域工作空间查询
list_domains	获取工作空间中的所有实体域	workspace：工作空间名称（必需） regionId：阿里云区域ID（必需）	- 在查询实体前先了解可用的域 - 了解数据分类情况

DoraAI工具集（AI智能洞察）

AI分析工具

工具名称	用途	关键参数	最佳实践
doraai_insight	AI智能洞察分析	query：查询问题（必需） 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 管理官方文档。

2. 当你初始化时候不传入 AccessKey 和 AccessKey Secret 时，会使用默认凭据链进行登录

   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_* 相关工具，请参考 日志服务权限说明，并授予必要的读取、查询等权限。
     • 应用实时监控服务 (ARMS)：如果您需要使用 arms_* 相关工具，请参考 ARMS 权限说明，并授予必要的查询权限。
   • 特殊权限说明，如果使用了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 管理

使用 pip 安装

⚠️ 需要 Python 3.10 及以上版本。

直接使用 pip 安装即可，安装命令如下：

# 安装（包含所有功能和依赖）
pip install mcp-server-aliyun-observability

1. 安装之后，直接运行即可，运行命令如下：

# 默认使用streamableHttp方式启动
python -m mcp_server_aliyun_observability

# 指定访问密钥启动
python -m mcp_server_aliyun_observability --access-key-id <your_access_key_id> --access-key-secret <your_access_key_secret>

# 使用SSE方式启动（用于远程访问）
python -m mcp_server_aliyun_observability --transport sse --transport-port 8000

可通过命令行传递指定参数:

• --transport 指定传输方式，可选值为 stdio、sse、streamable-http，默认值为 streamable-http
• --access-key-id 指定阿里云 AccessKeyId，不指定时会使用环境变量中的ALIBABA_CLOUD_ACCESS_KEY_ID
• --access-key-secret 指定阿里云 AccessKeySecret，不指定时会使用环境变量中的ALIBABA_CLOUD_ACCESS_KEY_SECRET
• --toolkits 指定要启用的工具包，逗号分隔。如 paas,iaas,doraai 或 all 启用所有（默认为 all）
• --log-level 指定日志级别，可选值为 DEBUG、INFO、WARNING、ERROR，默认值为 INFO
• --transport-port 指定传输端口，默认值为 8000，仅当 --transport 为 sse 时有效

使用 uvx 安装运行

# 使用 uvx 直接运行最新版本
uvx mcp-server-aliyun-observability

# 指定版本运行
uvx --from 'mcp-server-aliyun-observability==1.0.0' mcp-server-aliyun-observability

从源码安装

# clone 源码
git clone [e-mail]:aliyun/alibabacloud-observability-mcp-server.git
# 进入源码目录
cd alibabacloud-observability-mcp-server
# 安装
pip install -e .
# 运行
python -m mcp_server_aliyun_observability

Transport 选择指南

MCP服务器支持三种传输协议，选择合适的协议取决于您的使用场景：

Transport类型	适用场景	优势	限制
streamableHttp ✅	生产环境、Web应用（推荐）	- 现代HTTP流式协议 - 性能优异 - 生产级稳定性	- 需要网络配置
stdio	本地开发、命令行工具	- 最简单的集成方式 - 无网络配置要求 - 直接进程间通信	- 仅限本地使用 - 无法多客户端同时访问
sse (Server-Sent Events)	Web应用、远程访问	- 支持远程连接 - 基于标准HTTP协议 - 支持多客户端	- 需要维护长连接 - 性能较streamableHttp略低

💡 推荐使用: 生产环境和Web应用使用 streamableHttp（默认），本地开发使用 stdio，特殊场景使用 sse

AI 工具集成

Cursor，Cline 等集成

推荐方式：使用 streamableHttp（默认）

python -m mcp_server_aliyun_observability

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

使用 uvx 启动方式

{
  "mcpServers": {
    "alibaba_cloud_observability": {
      "command": "uvx",
      "args": [
        "mcp-server-aliyun-observability"
      ],
      "env": {
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "<your_access_key_id>",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "<your_access_key_secret>"
      }
    }
  }
}

使用 stdio 启动方式（本地开发）

{
  "mcpServers": {
    "alibaba_cloud_observability": {
      "command": "uvx",
      "args": [
        "mcp-server-aliyun-observability",
        "--transport",
        "stdio"
      ],
      "env": {
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "<your_access_key_id>",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "<your_access_key_secret>"
      }
    }
  }
}

Cherry Studio集成

Cursor集成

ChatWise集成