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...

Security Scan

The skill mostly matches its stated purpose (ZStack MCP integration) but includes mismatches and a clear risk: it ships a plaintext config with an API URL and admin password and its metadata omits the environment/credential needs it actually uses.

Purpose & Capability

The skill's name, description, scripts, and examples all align with providing a ZStack MCP integration and registering it with mcporter. However, the registry metadata claims 'required env vars: none' while SKILL.md and the scripts clearly expect and use ZSTACK_API_URL, ZSTACK_ACCOUNT, ZSTACK_PASSWORD or ZSTACK_SESSION_ID. Shipping a pre-filled config/zstack.env with an API URL and admin password is disproportionate to a general-purpose distribution (it embeds target-specific credentials).

Instruction Scope

Runtime instructions direct the agent/user to run interactive configuration, to save credentials into ~/clawd/skills/zstack-mcp/config/zstack.env, and to automatically update the user's mcporter config (~/.clawd/config/mcporter.json or ~/.team-os/mcp.json). Those actions are within the stated purpose (registering the MCP server) but they expand scope by persisting credentials and modifying user config files in the home directory. The SKILL.md also instructs use of curl requests and test commands that include credentials — all expected for this skill but worth noting because sensitive data is written to disk.

Install Mechanism

There is no aggressive install spec; SKILL.md recommends pip/pipx to install the upstream zstack-mcp-server package (a normal public registry flow). This is low-to-moderate risk. Nothing is downloaded from arbitrary shorteners or unknown URLs. However the repository bundle itself includes a pre-populated config file containing credentials, which increases practical risk during 'install' (copying the repo), even though the install mechanism is otherwise reasonable.

Credentials

The skill requires credentials (username/password or session ID) to function, which is appropriate, but the package contradicts registry metadata by not declaring required env vars. Worse, config/zstack.env in the package contains a plaintext ZSTACK_PASSWORD and ZSTACK_API_URL pointing at an internal IP (172.20.0.36) and an administrative password: 'AIOS@rootpswd123'. Bundling such credentials with a skill is unnecessary and dangerous — it may leak credentials or confuse users into using built-in credentials. The scripts will write credentials into the user's mcporter config, exposing them to any process that reads that file.

Persistence & Privilege

The skill does persist configuration to disk (skill-local config and modifies mcporter config in the user's home). It does not request 'always: true' and does not autonomously elevate privileges. Persisting credentials into home config is expected for an integration but increases attack surface and should be treated cautiously.

What to consider before installing

This skill implements a legitimate ZStack MCP integration but contains clear red flags you should address before installing or enabling it: - The package includes config/zstack.env with a plaintext admin password and an internal API URL. Do not use those credentials. Remove or overwrite config/zstack.env before running any scripts and rotate any real credentials if you accidentally used them. - The published metadata says no env vars are required, but the SKILL.md and scripts use ZSTACK_API_URL, ZSTACK_ACCOUNT, ZSTACK_PASSWORD or ZSTACK_SESSION_ID. Expect to supply these; verify where they will be stored (the scripts save them into ~/clawd/skills/zstack-mcp/config/zstack.env and add them to your mcporter config). - The scripts will modify your mcporter configuration file in your home directory. Inspect the scripts to confirm they only add the expected entry. Keep backups of mcporter config (scripts already create a .bak) and review the resulting JSON before trusting it. - Keep write operations disabled (do not set ZSTACK_ALLOW_ALL_API=true) unless you fully trust the environment and want the skill to perform destructive actions. - If you decide to proceed: (1) clone the repo into a safe place, (2) delete or sanitize config/zstack.env, (3) run configure.sh interactively to provide your own credentials (or supply a session ID), and (4) inspect the mcporter config changes created by register-mcp.sh before using them. Consider running initial tests in an isolated environment and verify the upstream pip package (zstack-mcp-server) is the expected project from its maintainers.

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",...}}'

配置说明

认证方式

方式	配置	说明
用户名密码	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

示例：

{
  "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