ZStack MCP Server

让 AI 能够动态查询和调用 ZStack Cloud 的 2000+ API 的 MCP Server。

功能特性

API 搜索: 根据关键词搜索 ZStack API，支持模糊匹配
API 描述: 获取 API 的详细参数说明
API 执行: 执行 ZStack API 并返回结果
监控指标搜索: 搜索可用的监控指标
监控数据获取: 获取指定指标的监控数据

安装

# 使用 pip 安装
pip install -e .

# 或者使用 uv
uv pip install -e .

配置

设置以下环境变量：

export ZSTACK_API_URL="http://localhost:8080"  # ZStack API 地址
export ZSTACK_ALLOW_ALL_API="false"             # 是否允许写操作（可选，默认 false）

# 认证方式一：用户名密码（会自动登录获取 Session）
export ZSTACK_ACCOUNT="admin"                   # 账户名
export ZSTACK_PASSWORD="your-password"          # 密码（明文）

# 认证方式二：直接传入 SessionID（优先级更高，设置后忽略用户名密码）
export ZSTACK_SESSION_ID="your-session-uuid"    # 已有的 Session UUID

认证方式说明

| 方式 | 环境变量 | 说明 | |------|----------|------| | 用户名密码 | ZSTACK_ACCOUNT + ZSTACK_PASSWORD | 自动登录获取 Session | | Session ID | ZSTACK_SESSION_ID | 直接使用已有 Session（优先级更高） |

💡 如果同时设置了 ZSTACK_SESSION_ID 和用户名密码，会优先使用 Session ID

安全说明

默认情况下，只允许调用只读 API，包括：

Query* - 查询类
Get* - 获取类
List* - 列表类
Describe* - 描述类
Check* - 检查类
Count* - 计数类
其他只读操作...

如需调用写操作 API（如 CreateVmInstance、DeleteVolume 等），需要设置：

export ZSTACK_ALLOW_ALL_API="true"

⚠️ 警告: 启用写操作后，AI 可以执行创建、删除、修改等危险操作，请谨慎使用！

使用方式

作为 MCP Server 运行

# 直接运行
python -m zstack_mcp.server

# 或使用入口点
zstack-mcp

SSE 模式运行

默认使用 stdio 传输。若需 SSE 模式，可用命令行或环境变量切换：

# 命令行方式
zstack-mcp --transport sse --host 0.0.0.0 --port 8000

# 环境变量方式
export MCP_TRANSPORT="sse"
export MCP_HOST="0.0.0.0"
export MCP_PORT="8000"
export MCP_PATH="/sse"  # 可选
zstack-mcp

说明：也兼容 FASTMCP_HOST / FASTMCP_PORT / FASTMCP_MOUNT_PATH（FastMCP 原生环境变量）

Streamable HTTP 模式运行

# 命令行方式
zstack-mcp --transport streamable-http --host 0.0.0.0 --port 8000 --streamable-path /mcp

# 环境变量方式
export MCP_TRANSPORT="streamable-http"
export MCP_HOST="0.0.0.0"
export MCP_PORT="8000"
export MCP_STREAMABLE_PATH="/mcp"  # 可选
zstack-mcp

说明：也兼容 FASTMCP_STREAMABLE_HTTP_PATH

在 Claude Desktop 中配置

在 claude_desktop_config.json 中添加：

方式一：使用用户名密码

{
  "mcpServers": {
    "zstack": {
      "command": "python",
      "args": ["-m", "zstack_mcp.server"],
      "env": {
        "ZSTACK_API_URL": "http://your-zstack-server:8080",
        "ZSTACK_ACCOUNT": "admin",
        "ZSTACK_PASSWORD": "your-password",
        "ZSTACK_ALLOW_ALL_API": "false"
      }
    }
  }
}

方式二：使用 Session ID

{
  "mcpServers": {
    "zstack": {
      "command": "python",
      "args": ["-m", "zstack_mcp.server"],
      "env": {
        "ZSTACK_API_URL": "http://your-zstack-server:8080",
        "ZSTACK_SESSION_ID": "your-session-uuid",
        "ZSTACK_ALLOW_ALL_API": "false"
      }
    }
  }
}

💡 将 ZSTACK_ALLOW_ALL_API 设为 "true" 可启用写操作（创建/删除/修改等）

可用工具

1. search_api

根据关键词搜索 ZStack API。

参数:

keywords (list[str]): 搜索关键词，如 ["Query", "Vm"]
category (str, 可选): 按分类过滤
limit (int, 默认 15): 最多返回数量

2. describe_api

获取指定 API 的详细参数说明。

参数:

api_name (str): API 名称，如 "QueryVmInstance"

3. execute_api

执行 ZStack API。

参数:

api_name (str): API 名称
parameters (dict): API 参数

4. search_metric

搜索可用的监控指标。

参数:

keywords (list[str]): 搜索关键词
namespace (str, 可选): 按命名空间过滤（支持模糊匹配，如 vm/host）
limit (int, 默认 20): 最多返回数量
match_mode (str, 默认 or): 关键词匹配模式（and/or）
prefer_namespaces (list[str], 可选): 优先排序的命名空间列表（默认 ["ZStack/VM","ZStack/Host"]）

💡 提示：不确定 namespace 时可先不传，返回结果会带 namespace 值供选择 💡 默认 match_mode=or（多关键词并集）；如需交集请显式传 and 💡 指标名称在不同 namespace 可能重名，建议指定 namespace 或 prefer_namespaces 以确保排序优先

5. get_metric_data

获取监控数据。

参数:

namespace (str): 命名空间
metric_name (str): 指标名称
start_time (str|int, 可选): 开始时间 (ISO 或秒级时间戳)
end_time (str|int, 可选): 结束时间 (ISO 或秒级时间戳)
period (int, 默认 60): 采样周期(秒)
labels (list[str]|dict, 可选): 标签过滤，如 ["VMUuid=xxx"] 或 {"VMUuid":"xxx"}
summary_only (bool, 可选): 仅返回统计信息（点数/最大/最小/平均/方差/标准差）

数据量提示:

返回点数估算：ceil((end_time - start_time) / period) * series_count
series_count 为不同 label 组合数量；不传 labels 时可能返回多组序列
建议通过缩短时间范围、增大 period 或增加 labels 过滤避免输出过大

6. get_metric_summary

获取监控指标的聚合 TopN（按 label_key 分组）。

参数:

namespace (str): 命名空间
metric_name (str): 指标名称
label_key (str): 标签键，如 VMUuid/HostUuid
metric_names (list[str], 可选): 多指标合并（如 in/out）
start_time (str|int, 可选): 开始时间 (ISO 或秒级时间戳)
end_time (str|int, 可选): 结束时间 (ISO 或秒级时间戳)
period (int, 默认 60): 采样周期(秒)
aggregate (str, 默认 max): 单指标聚合方式 (max/avg/sum/min)
combine (str, 默认 sum): 多指标合并方式 (sum/avg/max/min)
threshold_op (str, 可选): 阈值比较符 (>,>=,<,<=,==,!=)
threshold_value (number, 可选): 阈值数值
top_n (int, 默认 10): 返回条数
resolve_resource (str, 可选): vm 或 host，用于解析名称

Query API 条件语法

对于 Query 类 API，conditions 参数支持以下操作符：

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

conditions 格式:

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

示例交互

用户问: "帮我查一下 UUID 为 ae6e57a0 开头的 VM 的详情"

AI 会:

调用 search_api(keywords=["Query", "Vm", "Instance"])
调用 describe_api(api_name="QueryVmInstance")
调用 execute_api(api_name="QueryVmInstance", parameters={"conditions": [{"name": "uuid", "op": "?=", "value": "ae6e57a0%"}]})

开发

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

License

MIT

MCP Servers