alibabacloud-ack-mcp-server 1.0.2

AlibabaCloud Container Service MCP Server (ack-mcp-server)

阿里云容器服务 MCP Server (ack-mcp-server)

阿里云容器服务MCP Server工具集: ack-mcp-server。
将 ACK 集群/资源管理、Kubernetes 原生操作与容器场景的可观测性能力、安全审计、诊断巡检等运维能力统一为AI原生的标准化工具集。
本工具集的能力被阿里云容器服务智能助手功能集成。也可支持三方AI Agent (kubectl-ai、QWen Code、Claude Code、Cursor、Gemini CLI、VS Code等)或自动化系统调用集成，基于 MCP（Model Context Protocol）协议。
实现支持通过自然语言与 AI 助手交互，完成复杂的容器运维任务。帮助构建用户自己的容器场景AIOps运维体系。

• 1. 概述 & 功能简介
• 2. 如何使用 & 部署
• 3. 如何本地开发运行
• 4. 如何参与社区贡献
• 5. 效果-benchmark
• 6. 演进计划-roadmap
• 7. 常见问题

🌟 1. 概述 & 功能简介

🎬 1.1 演示效果

https://github.com/user-attachments/assets/9e48cac3-0af1-424c-9f16-3862d047cc68

🎯 1.2 核心功能

阿里云 ACK 全生命周期的资源管理

• 集群查询 (list_clusters)
• 节点资源管理、节点池扩缩容 (Later)
• 组件Addon管理 (Later)
• 集群创建、删除 (Later)
• 集群升级 (Later)
• 集群资源运维任务查询 (Later)

Kubernetes 原生操作 (ack_kubectl)

• 执行 kubectl 类操作（读写权限可控）
• 获取日志、事件，资源的增删改查
• 支持所有标准 Kubernetes API

AI原生的容器场景可观测性

• Prometheus: 支持ACK集群对应的阿里云Prometheus、自建Prometheus的指标查询、自然语言转 PromQL (query_prometheus / query_prometheus_metric_guidance)
• 集群控制面日志查询: 支持ACK集群的控制面SLS 日志的查询，包括SLS SQL 查询、自然语言转 SLS-SQL (query_controlplane_logs)
• 审计日志: Kubernetes 操作审计追踪 (query_audit_log)
• …… (更多容器可观测能力 ing)

阿里云 ACK 诊断、巡检功能

• 集群资源诊断 (diagnose_resource)
• 集群健康巡检 (query_inspect_report)

企业级工程能力

• 🏗️ 分层架构：工具层、服务层、认证层完全解耦
• 🔐 动态凭证注入：支持请求级 AK 注入或环境凭证
• 📊 健壮错误处理：结构化错误输出与类型化响应
• 📦 模块化设计：各子服务可独立运行

🏆 1.3 核心优势

• 🤖 AI 原生: 专为 AI 代理设计的标准化接口
• 🔧 统一工具集: 一站式容器运维能力整合
• ⚡ 知识沉淀: 内置ACK、K8s、容器可观测体系的最佳实践经验沉淀
• 🛡️ 企业级: 完善的认证、授权、日志机制
• 📈 可扩展: 插件化架构，轻松扩展新功能

📈 1.4 Benchmark 效果验证 (持续更新中)

基于实际场景的 AI 能力测评，支持多种 AI 代理和大模型的效果对比：

任务场景	AI Agent	大模型	成功率	平均处理时间
Pod OOM 修复	qwen_code	qwen3-coder-plus	✅ 100%	2.3min
集群健康检查	qwen_code	qwen3-coder-plus	✅ 95%	6.4min
资源异常诊断	kubectl-ai	qwen3-32b	✅ 90%	4.1min
历史资源分析	qwen_code	qwen3-coder-plus	✅ 85%	3.8min

最新 Benchmark 报告参见 benchmarks/results/ 目录。

---

🚀 2. 如何使用 & 部署

💻 2.1 阿里云认证、权限准备

建议为ack-mcp-server配置的阿里云账号认证为一个主账号的子账号，并遵循最小权限原则，为此子账号赋予如下权限策略集。

所需RAM权限策略集

如何为阿里云账号的RAM账号添加所需权限，参考文档：RAM 权限策略
当前ack-mcp-server所需只读权限集为：

• 容器服务cs 所有只读权限
• 日志服务log 所有只读权限
• 阿里云prometheus(arms) 实例只读权限
• ……后续追加资源变更权限以支持资源全生命周期管理

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cs:Check*",
        "cs:Describe*",
        "cs:Get*",
        "cs:List*",
        "cs:Query*",
        "cs:RunClusterCheck",
        "cs:RunClusterInspect"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "arms:GetPrometheusInstance",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "log:Describe*",
        "log:Get*",
        "log:List*"
      ],
      "Resource": "*"
    }
  ]
}

💻 2.2 （可选）创建ACK集群

• 阿里云账号中已创建的 ACK 集群
• 需要生成的集群网络可访问的情况下，配置对应的Kubernetes集群访问凭证，参考配置方式，在生产环境建议打通集群网络后，通过配置KUBECONFIG_MODE = ACK_PRIVATE，通过内网访问集群。

📍 2.3 部署运行ack-mcp-server

2.3.1 部署方式1 - 使用 Helm 部署在k8s集群内

在 Kubernetes 集群中部署：

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

# 使用 Helm 部署
helm install \
--set accessKeyId=<your-access-key-id> \
--set accessKeySecret=<your-access-key-secret> \
--set transport=sse \
ack-mcp-server \
./deploy/helm \
-n kube-system 

部署后通过为ack-mcp-server service配置负载均衡等方式透出外网访问服务，以对接AI Agent。

参数说明

• accessKeyId: 阿里云账号的 AccessKeyId
• accessKeySecret: 阿里云账号的 AccessKeySecret

2.3.2 部署方式2 - 📦 使用 Docker 镜像部署ack-mcp-server

# 拉取镜像
docker pull registry-cn-beijing.ack.aliyuncs.com/acs/ack-mcp-server:latest

# 运行容器
docker run \ 
  -d \
  --name ack-mcp-server \
  -e ACCESS_KEY_ID="your-access-key-id" \
  -e ACCESS_KEY_SECRET="your-access-key-secret" \
  -p 8000:8000 \
  registry-cn-beijing.ack.aliyuncs.com/acs/ack-mcp-server:latest \
  python -m main_server --transport sse --host 0.0.0.0 --port 8000 --allow-write

2.3.3 部署方式3 - 💻 使用 Binary 方式启动部署

下载预编译的二进制文件 或 本地构建二进制文件后运行：

# 构建二进制文件（本地构建）
make build-binary

# 运行
./dist/binary/ack-mcp-server --help

2.3.4 部署方式3 - 与 Gemini CLI extensions 集成

# Gemini CLI
gemini extensions install https://github.com/aliyun/alibabacloud-ack-mcp-server --ref master --auto-update

# Verify:
gemini extensions list

通过环境变量 或 <home>/.gemini/extensions/ack-mcp-server/.env 文件配置参数

运行 gemini

2.4 通过 Agent 使用 ack-mcp-server

2.4.1 Qwen Code

qwen mcp add --transport http --scope user ack-mcp-server <endpoint>

# Verify:
qwen mcp list

2.4.2 Qoder CLI

qodercli mcp add --transport http --scope user ack-mcp-server <endpoint>

# Verify:
qodercli mcp list

2.4.3 Gemini CLI

gemini mcp add --transport http --scope user ack-mcp-server <endpoint>

# Verify:
gemini mcp list

2.4.4 Claude Code

claude mcp add --transport http --scope user ack-mcp-server <endpoint>

# Verify:
claude mcp list

2.4.5 Codex CLI

codex mcp add ack-mcp-server --url <endpoint>

# Verify:
codex mcp list

🎯 3 如何本地开发运行

💻 3.1 环境准备

构建环境要求

• Python 3.12+
• 阿里云账号及 AccessKey、AccessSecretKey，所需权限集
• 阿里云账号中已创建的 ACK 集群
• 配置ACK集群可被ack-mcp-server本地网络可访问的kubeconfig配置，参考配置方式。
  • 注：推荐在生产环境建议打通集群网络后，通过配置KUBECONFIG_MODE = ACK_PRIVATE，通过内网访问集群。本地测试使用公网访问集群kubeconfig需在对应ACK开启公网访问kubeconfig。

📋 3.2 开发环境搭建

# 克隆项目
git clone https://github.com/aliyun/alibabacloud-ack-mcp-server
cd alibabacloud-ack-mcp-server

# 安装依赖
uv sync

# 激活虚拟环境(Bash)
source .venv/bin/activate

# 配置环境
cp .env.example .env
vim .env

# 运行开发服务
make run

安装依赖

使用 uv（推荐）：

uv sync
source .venv/bin/activate

或使用 pip：

pip install -r requirements.txt

⚙️ 3.3 配置设置

创建 .env 文件（可参考 .env.example）：

# 阿里云凭证与地域
ACCESS_KEY_ID=your-access-key-id
ACCESS_KEY_SECRET=your-access-key-secret

# 缓存配置
CACHE_TTL=300
CACHE_MAX_SIZE=1000

# 日志配置
FASTMCP_LOG_LEVEL=INFO
DEVELOPMENT=false

⚠️ 注意: 未设置 ACCESS_KEY_ID/ACCESS_KEY_SECRET 时，部分依赖云 API 的功能不可用。

3.4.1 运行模式1. 基于 MCP Inspector 的交互界面（适合本地效果调试）

npx @modelcontextprotocol/inspector --config ./mcp.json

3.4.2 本地python命令运行ack-mcp-server

本地运行ack-mcp-server Stdio 模式（适合本地开发）

make run
# 或
python -m src.main_server

本地运行ack-mcp-server Streaming HTTP 模式（推荐线上系统集成使用）

make run-http
# 或
python -m src.main_server --transport http --host 0.0.0.0 --port 8000

本地运行ack-mcp-server SSE 模式

make run-sse
# 或
python -m src.main_server --transport sse --host 0.0.0.0 --port 8000

常用参数

参数	说明	默认值
--access-key-id	AccessKey ID	阿里云账号凭证AK
--access-key-secret	AccessKey Secret	阿里云账号凭证SK
--allow-write	启用写入操作	默认不启动
--transport	传输模式	stdio / sse / http
--host	绑定主机	localhost
--port	端口号	8000

3.5. 功能测试UT

# 运行全部测试UT
make test

🛠️ 4. 如何参与社区贡献

🏗️ 4.1 工程架构设计

技术栈: Python 3.12+ + FastMCP 2.12.2+ + 阿里云SDK + Kubernetes Client

详细架构设计参见 DESIGN.md。

👥 4.2 项目维护机制

🤝 如何贡献

1. 问题反馈: 通过 GitHub Issues
2. 功能请求: 通过 即时通信钉钉群： 70080006301 讨论沟通
3. 代码贡献: Fork → 功能分支 → Pull Request
4. 文档改进: API 文档、教程编写

💬 社区交流

• GitHub Discussions through Issues: 技术讨论、问答
• 钉钉群: 日常交流、答疑支持、社区共建。 搜索钉钉群号： 70080006301

---

📊 5. 效果 & Benchmark （持续构建中）

🔍 测试场景

场景	描述	涉及模块
Pod OOM 修复	内存溢出问题诊断修复	kubectl, 诊断
集群健康检查	全面的集群状态巡检	诊断, 巡检
资源异常诊断	异常资源根因分析	kubectl, 诊断
历史资源分析	资源使用趋势分析	prometheus, sls

📊 效果数据

基于最新 Benchmark 结果：

• 成功率: 92%
• 平均处理时间: 4.2分钟
• 支持 AI 代理: qwen_code, kubectl-ai
• 支持 LLM: qwen3-coder-plus, qwen3-32b

如何运行benchmark

详细参见 Benchmark README.md。

# 运行 Benchmark
cd benchmarks
./run_benchmark.sh --openai-api-key your-key --agent qwen_code --model qwen3-coder-plus

---

🗺️ 6. 演进计划 & Roadmap

🎯 近期计划

• 支持ACK 集群、节点、功能承载组件(addon)的全生命周期资源运维
• 以benchmark效果作为基线目标，持续优化核心场景在通用三方Agent、LLM model中的效果，提升核心运维场景的效果成功率
• 持续补充benchmark的核心运维场景case，覆盖ACK大部分运维场景，如有需求，欢迎提issue
• 性能优化与缓存改进

🚀 中长期目标

• 覆盖容器场景的卓越架构的五大支柱：安全、稳定、成本、效率、性能(高可靠性等)的能力，对多步骤的复杂容器运维场景，提供更优秀的AIOps体验。
• • 集群成本的洞察与治理
• • 集群弹性伸缩的最佳实践
• • 集群的安全漏洞发现与治理
• • ……
• 企业级特性（RBAC, 安全扫描）
• AI 自动化运维能力

7. 常见问题

• 未配置 AK: 请检查 ACCESS_KEY_ID/ACCESS_KEY_SECRET 环境变量
• ACK集群网络不可访问: 当ack-mcp-server使用 KUBECONFIG_MODE = ACK_PUBLIC 公网方式访问集群kubeconfig，需要ACK集群开启公网访问的kubeconfig，在生产环境中推荐打通集群网络，并使用 ACK_PRIVATE 私网方式访问集群kubeconfig，以遵守生产安全最佳实践。

8. 安全

• 请发送邮件到 [e-mail] 报告安全漏洞。详细信息请参阅 SECURITY.md 文件。

许可证

Apache-2.0。详见 LICENSE。