Skip to content
BranchesTags

Repository files navigation

ZStack MCP Server

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

功能特性

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

安装

# 从 PyPI 安装
pip install zstack-mcp-server
# 或者使用 uv
uv pip install zstack-mcp-server

💡 也可以不安装，直接用 uvx 或 pipx run 一键运行（见下方使用方式）

配置

设置以下环境变量：

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# 查询响应控制（可选）export ZSTACK_QUERY_DEFAULT_LIMIT="50"# Query API 默认 limit（设 0 禁用）export ZSTACK_RESPONSE_SIZE_LIMIT="65536"# 响应大小上限，字节（设 0 禁用）

认证方式说明

方式环境变量说明
用户名密码ZSTACK_ACCOUNT + ZSTACK_PASSWORD自动登录获取 Session
Session IDZSTACK_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 可以执行创建、删除、修改等危险操作，请谨慎使用！

查询响应控制

Query API 默认注入 limit=50，防止一次拉取全量数据撑满模型上下文窗口。响应超过 64KB 时会自动裁剪 inventories 列表，保证返回合法 JSON。

环境变量默认值说明
ZSTACK_QUERY_DEFAULT_LIMIT50Query API 未指定 limit 时自动注入的默认值，设 0 禁用
ZSTACK_RESPONSE_SIZE_LIMIT65536响应大小上限（字节），超过后裁剪，设 0 禁用
  • 显式传入 limit 时不会被覆盖
  • 裁剪发生时响应中会包含 _truncation 字段，提示使用 limit/start 翻页或 fields 精简返回字段

使用方式

作为 MCP Server 运行

# 使用 uvx 直接运行（无需安装）
uvx zstack-mcp-server
# 或使用 pipx
pipx run zstack-mcp-server
# 如果已安装，直接运行
zstack-mcp-server

SSE 模式运行

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

# 命令行方式
uvx zstack-mcp-server --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"# 可选
uvx zstack-mcp-server

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

Streamable HTTP 模式运行

# 命令行方式
uvx zstack-mcp-server --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"# 可选
uvx zstack-mcp-server

说明：也兼容 FASTMCP_STREAMABLE_HTTP_PATH

HTTP 头认证（多租户模式）

在 SSE 或 streamable-http 模式下，管理员可以启动一个共享的 MCP Server，多个用户通过 HTTP 头传入各自的凭据，实现多租户隔离。

支持的 HTTP 头：

HTTP Header对应环境变量说明
X-ZStack-AccountZSTACK_ACCOUNT账户名
X-ZStack-PasswordZSTACK_PASSWORD密码
X-ZStack-Session-IdZSTACK_SESSION_ID已有 Session（优先级高于账号密码）
X-ZStack-API-URLZSTACK_API_URLZStack 管理节点地址（可代理多套环境）

凭据优先级：HTTP 头 > 环境变量

典型用法：

# 管理员启动共享 MCP Server
ZSTACK_ALLOW_ALL_API=false uvx zstack-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

用户在 MCP 客户端配置中添加 HTTP 头即可使用各自的账号：

{
"mcpServers": {
"zstack": {
"transport": "streamable-http",
"url": "http://mcp-server:8000/mcp",
"headers": {
"X-ZStack-Account": "user-a",
"X-ZStack-Password": "password-a",
"X-ZStack-API-URL": "http://zstack-env-1:8080"
}
}
}
}

特性：

  • 同一账号的 Session 会自动缓存复用，不会每次请求都创建新 Session
  • 不同 X-ZStack-API-URL 的请求会路由到不同的 ZStack 环境
  • stdio 模式下无 HTTP 头，自动回退到环境变量认证，行为不变

在 Claude Desktop 中配置

在 claude_desktop_config.json 中添加：

方式一：使用用户名密码

{
"mcpServers": {
"zstack": {
"command": "uvx",
"args": ["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": "uvx",
"args": ["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 会:

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

开发

# 克隆仓库
git clone https://github.com/zstackio/zstack-mcp-server.git
cd zstack-mcp-server
# 安装开发依赖
pip install -e ".[dev]"# 运行测试
pytest

License

MIT

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

11 stars

Watchers

0 watching

Forks

5 forks
Report repository

Releases

Packages

Contributors

Languages