zstack-mcp（zstack MCP 搜索）

ZStack MCP Skill

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

快速开始

1. 安装依赖

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

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

2. 配置认证

# 运行配置脚本（交互式，会自动测试登录）
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

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

使用示例

搜索 API

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

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

获取 API 详情

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

执行 API

# 查询所有虚拟机
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}}'

监控指标

# 搜索监控指标
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"]}'

写操作（需显式启用）

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

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

配置说明

认证方式

环境变量

配置文件位置

• 认证配置: ~/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 参数支持以下操作符：

示例：

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

故障排查

# 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
• 或使用用户名密码认证（自动登录）

多机器部署

# 通过 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