Alibaba Cloud Observability MCP Server (Go Version)

📌 Important Note

This project has been refactored using Go. If you need to use the original Python version, please visit the v1 directory:

• 📖 v1/README.md - Python version documentation

• 📦 The Python version can be installed via pip install mcp-server-aliyun-observability

This is the Go implementation of the Alibaba Cloud Observability MCP Server, providing AI models with structured data access capabilities for Alibaba Cloud Log Service (SLS) and CloudMonitor (CMS). Based on the Model Context Protocol, it integrates seamlessly with AI tools such as Cursor, Kiro, Cline, and Windsurf.

Features

• Supports three transport modes: stdio, SSE, and streamable-http

• Modular toolset architecture: PaaS (CloudMonitor 2.0), IaaS (direct SLS/CMS access), Shared

• Flexible time expression parsing: relative time, absolute timestamps, Grafana-style, and preset keywords

• Time-series data comparative analysis: statistical calculation, trend analysis, and difference scoring

• Structured error handling: English error descriptions and solution suggestions

• Stability guarantees: retries (exponential backoff), circuit breakers, and graceful shutdown

• Structured JSON logging (slog)

• Single binary file, zero runtime dependencies

Related MCP server: AlibabaCloud DevOps MCP Server

Quick Start

Download and Installation

Download the binary for your platform from the Releases page:

# 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

After extraction, it contains:

• alibabacloud-observability-mcp-server - Executable file

• config.yaml - Default configuration file

Configure Credentials

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

How to obtain AccessKey: Alibaba Cloud AccessKey Management

Start the Service

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

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

CLI Commands

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

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

Building from Source

Prerequisites

• Go 1.23+

Build

# 克隆仓库
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

The generated binary is located in the bin/ directory.

Configuration

Configuration uses a two-layer structure:

1. config.yaml - Server configuration (transport mode, logging, network, etc.)

2. .env file or environment variables - Credentials and runtime parameters

Configuration Files

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

config.yaml search path: current directory → ./config/

.env files are loaded from the current directory, suitable for storing credentials that should not be committed to version control.

config.yaml Structure

# 服务器配置
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"

Fine-grained Tool Selection

By default, toolkit.scope controls tool enablement by category (all/paas/iaas). If more granular control is needed, you can use toolkit.enabled_tools to specify the list of tools to enable:

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

When enabled_tools is not empty, only the tools in the list will be registered, and the rest will be unavailable. scope still determines which toolkit modules are loaded, and enabled_tools further filters them on top of that.

For the complete list of tools and category descriptions, please refer to the comment template in config.yaml.

CLI Arguments

Environment Variables (Credentials and Runtime Parameters)

• When AccessKey is not configured, the service will automatically use the Default Credential Chain to obtain credentials (supporting ECS RAM Role, OIDC, configuration files, etc.). Manual AccessKey configuration is not required in cloud environments like ECS or Function Compute.

Credential resolution priority: CLI arguments / .env file > shell environment variables > default credential chain.

💡 Automatic Default Value Filling

When ALIBABA_CLOUD_REGION or ALIBABA_CLOUD_WORKSPACE is set, if regionId or workspace parameters are not provided in the tool call, the service will automatically use the values from the environment variables as defaults. Values explicitly passed by the user will not be overwritten.

AI Tool Integration

Cursor / Kiro / Cline

streamable-http mode (Recommended):

1. Configure config.yaml (set server.transport: streamable-http)

2. Start the service:

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

3. Configure mcp.json:

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

stdio mode:

1. Configure 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>"
      }
    }
  }
}

Note: In stdio mode, if config.yaml does not exist, built-in default values will be used.

Toolsets

There are 33 tools in total, divided into three levels.

PaaS Toolset (CloudMonitor 2.0, Recommended)

Based on a unified data model, tool names are prefixed with umodel_ or cms_. There are 16 tools in total.

Entity Management Tools

Dataset Management Tools

Data Query Tools

IaaS Toolset (Direct SLS/CMS Access)

Direct access to underlying APIs, tool names are prefixed with sls_ or cms_. There are 14 tools in total.

SLS Tools

CMS Tools

Shared Toolset

There are 3 tools in total.

Time Expressions

All data query tools support flexible time range formats:

Advanced Features

Time-Series Comparative Analysis

umodel_get_metrics and umodel_get_golden_metrics support time-series comparison via the offset parameter:

# 对比当前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"
)

The returned result includes:

• current: Statistics for the current period (max, min, avg, count)

• compare: Statistics for the comparison period

• diff: Change analysis (trend, avg_change, avg_change_percent)

• diff_score: Difference score (0-1, the higher the value, the more significant the difference)

Advanced Analysis Modes

umodel_get_metrics supports four analysis modes:

Project Structure

├── 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

Development

# 构建
make build

# 运行测试
make test

# 代码检查
make lint

# 清理构建产物
make clean

Testing

The project adopts a three-track strategy: unit testing + property-based testing + regression testing:

• Unit testing: Table-driven tests, covering specific examples and boundary conditions

• Property-based testing: Using gopter to verify general correctness properties across all inputs

• Regression testing: Integration tests (//go:build integration), comparing parameter consistency with the Python version, requiring real Alibaba Cloud credentials

# 运行所有单元测试
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 Development Guidelines

See docs/AGENTS.md, which includes project structure explanations, code style conventions, procedures for adding new tools, testing specifications, etc.

Permissions Requirements

To ensure the MCP Server can successfully access and operate your Alibaba Cloud observability resources, you need to configure the following permissions:

Alibaba Cloud AccessKey

• The service requires valid Alibaba Cloud credentials to run, supporting the following methods (in order of priority):

  1. AccessKey ID + AccessKey Secret (passed via .env file, environment variables, or CLI arguments)

  2. STS temporary credentials (set ALIBABA_CLOUD_SECURITY_TOKEN environment variable)

  3. Default Credential Chain automatic discovery (ECS RAM Role, OIDC, credential configuration files, etc.)

• To obtain and manage AccessKey, please refer to the official Alibaba Cloud AccessKey Management documentation

RAM Authorization

The RAM user or role associated with the AccessKey must be granted the necessary permissions to access the relevant cloud services.

It is strongly recommended to follow the "Principle of Least Privilege": grant only the minimum set of permissions necessary to run the MCP tools you plan to use.

Depending on the tools you need to use, refer to the following documentation for permission configuration:

Special Permission Notes:

• Using SQL generation tools (e.g., sls_text_to_sql) requires separate sls:CallAiTools permission

• Using natural language query functionality (cms_natural_language_query) requires granting: cms:CreateChat, cms:CreateThread, cms:GetThread, cms:ListThreads

Security Recommendations

• The service does not store AccessKeys; they are only used for API calls at runtime

• In SSE/HTTP mode, ensure you implement access control for the endpoint yourself

• It is recommended to deploy within an internal network or VPC to avoid direct exposure to the public internet

• Never expose a server endpoint configured with an AccessKey to the public internet without authentication

• It is recommended to use Alibaba Cloud Function Compute (FC) for deployment and configure it for access only within the VPC

License

This project follows the same license agreement as the original Python version.