Zstack Mcp

ZStack Cloud MCP Server integration for OpenClaw. Enables AI to query and execute ZStack APIs (2000+ endpoints) with authentication management and read-only safety.

ZStack MCP Skill

让 OpenClaw 通过 MCP 协议调用 ZStack Cloud 2000+ API。

快速开始

1. 安装依赖

bash

# 安装 ZStack MCP Server（推荐用 pipx 隔离环境）
pipx install zstack-mcp-server

# 或使用 pip
pip install zstack-mcp-server

2. 配置认证

bash

# 运行配置脚本（交互式，会自动测试登录）
bash ~/clawd/skills/zstack-mcp/scripts/configure.sh

脚本会提示输入：

• ZStack API 地址（如 http://172.20.0.36:8080）
• 用户名（默认 admin）
• 密码

配置保存到 ~/clawd/skills/zstack-mcp/config/zstack.env

3. 注册到 mcporter

bash

# 自动注册到 ~/clawd/config/mcporter.json
bash ~/clawd/skills/zstack-mcp/scripts/register-mcp.sh

使用示例

搜索 API

bash

# 搜索包含关键词的 API
mcporter call zstack-mcp.search_api --args '{"keywords":["Query","Vm"]}'

# 按分类过滤
mcporter call zstack-mcp.search_api --args '{"keywords":["Vm"],"category":"vm"}'

获取 API 详情

bash

mcporter call zstack-mcp.describe_api --args '{"api_name":"QueryVmInstance"}'

执行 API

bash

# 查询所有虚拟机
mcporter call zstack-mcp.execute_api --args '{"api_name":"QueryVmInstance","parameters":{"conditions":[]}}'

# 查询运行中的 VM（使用 conditions 过滤）
mcporter call zstack-mcp.execute_api --args '{"api_name":"QueryVmInstance","parameters":{"conditions":[{"name":"state","op":"=","value":"Running"}]}}'

# 指定返回字段（减少响应大小）
mcporter call zstack-mcp.execute_api --args '{"api_name":"QueryVmInstance","parameters":{"conditions":[],"fields":["uuid","name","cpuNum","memorySize","state"]}}'

# 分页查询
mcporter call zstack-mcp.execute_api --args '{"api_name":"QueryVmInstance","parameters":{"conditions":[],"limit":20,"start":0}}'

监控指标

bash

# 搜索监控指标
mcporter call zstack-mcp.search_metrics --args '{"keywords":["cpu","vm"]}'

# 获取监控数据
mcporter call zstack-mcp.get_metric_data --args '{"namespace":"ZStack/VM","metric_name":"cpuUtilization","labels":["VMUuid=xxx"]}'

写操作（需显式启用）

bash

# 编辑配置文件添加环境变量
# ZSTACK_ALLOW_ALL_API="true"

# 创建虚拟机（危险操作！）
mcporter call zstack-mcp.execute_api --args '{"api_name":"CreateVmInstance","parameters":{"name":"test-vm",...}}'

配置说明

认证方式

方式	配置	说明
用户名密码	ZSTACK_ACCOUNT + ZSTACK_PASSWORD	自动登录获取 Session，推荐
Session ID	ZSTACK_SESSION_ID	直接使用已有 Session，优先级更高

环境变量

变量	说明	默认值
ZSTACK_API_URL	ZStack API 地址	必填
ZSTACK_ACCOUNT	账户名	admin
ZSTACK_PASSWORD	密码	必填
ZSTACK_SESSION_ID	Session UUID（优先级更高）	-
ZSTACK_ALLOW_ALL_API	允许写操作	false
ZSTACK_QUERY_DEFAULT_LIMIT	Query API 默认 limit	50
ZSTACK_RESPONSE_SIZE_LIMIT	响应大小上限（字节）	65536

配置文件位置

• 认证配置: ~/clawd/skills/zstack-mcp/config/zstack.env
• MCP 配置: ~/clawd/config/mcporter.json（优先）或 ~/.team-os/mcp.json

安全说明

• 默认只读：只允许 Query*, Get*, List*, Describe*, Check*, Count* 等查询类 API
• 写操作需显式启用：设置 ZSTACK_ALLOW_ALL_API="true"
• 响应限制：默认 64KB 限制，防止撑爆模型上下文
• Session 管理：SessionID 会过期，建议使用用户名密码自动登录

API 条件语法

Query 类 API 的 conditions 参数支持以下操作符：

操作符	含义	示例
=	等于	name=test
!=	不等于	state!=Deleted
>	大于	cpuNum>4
>=	大于等于	memorySize>=1073741824
<	小于	createDate<2024-01-01
<=	小于等于	-
?=	模糊匹配 (LIKE)	name?=%test%
!?=	模糊不匹配	name!?=%test%
~=	正则匹配	name~=.*test.*
!~=	正则不匹配	-
=null	为空	description=null
!=null	不为空	-
in	在列表中	state?=Running,Stopped
not in	不在列表中	state!?=Deleted,Destroyed

示例：

json

{
  "conditions": [
    {"name": "uuid", "op": "?=", "value": "ae6e57a0%"},
    {"name": "state", "op": "in", "value": "Running,Stopped"}
  ]
}

故障排查

bash

# 1. 检查 mcporter 配置
mcporter config list

# 2. 测试 MCP 连接
mcporter call zstack-mcp.search_api --args '{"keywords":["Query"]}'

# 3. 查看 MCP server 日志
mcporter daemon status

# 4. 手动测试 ZStack API 连接
source ~/clawd/skills/zstack-mcp/config/zstack.env
curl -X POST "$ZSTACK_API_URL/zstack/api" \
  -H "Content-Type: application/json" \
  -d "{\"org.zstack.header.identity.APILoginMessage\":{\"accountName\":\"$ZSTACK_ACCOUNT\",\"password\":\"$ZSTACK_PASSWORD\"}}"

常见问题

Q: 提示 "Unknown MCP server 'zstack-mcp'"

• 检查配置文件路径：cat ~/clawd/config/mcporter.json
• 确认配置已加载：mcporter config list

Q: 响应被截断

• 使用 fields 参数精简返回字段
• 使用 limit 和 start 分页
• 增大 ZSTACK_RESPONSE_SIZE_LIMIT（不推荐）

Q: Session 过期

• 重新运行 configure.sh 获取新 SessionID
• 或使用用户名密码认证（自动登录）

多机器部署

bash

# 通过 ClawHub 安装
clawhub install zstack-mcp

# 配置认证
bash ~/clawd/skills/zstack-mcp/scripts/configure.sh

# 注册到 mcporter
bash ~/clawd/skills/zstack-mcp/scripts/register-mcp.sh

参考

• ZStack MCP Server
• mcporter Skill