ZSvirt MCP Server

An MCP Server that enables AI to dynamically query and call ZSvirt's 2000+ APIs.

Features

• API Search: Search ZStack APIs by keyword, with fuzzy matching support

• API Description: Get detailed parameter descriptions for an API

• API Execution: Execute ZStack APIs and return results

• Metric Search: Search available monitoring metrics

• Metric Data Retrieval: Get monitoring data for specified metrics

Installation

# 从 PyPI 安装
pip install zsvirt-mcp-server

# 或者使用 uv
uv pip install zsvirt-mcp-server

💡 You can also skip installation and run it directly with uvx or pipx run (see Usage below).

Configuration

Set the following environment variables:

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 禁用）

Authentication Methods

💡 If both ZSTACK_SESSION_ID and username/password are set, the Session ID takes precedence.

Security Notes

By default, only read-only APIs are allowed, including:

• Query* - Query operations

• Get* - Get operations

• List* - List operations

• Describe* - Describe operations

• Check* - Check operations

• Count* - Count operations

• Other read-only operations...

To call write-operation APIs (such as CreateVmInstance, DeleteVolume, etc.), you need to set:

export ZSTACK_ALLOW_ALL_API="true"

⚠️ Warning: Once write operations are enabled, the AI can perform dangerous actions such as creating, deleting, and modifying resources. Use with caution!

Query Response Control

Query APIs inject limit=50 by default to prevent pulling all data at once and overflowing the model context window. When the response exceeds 64KB, the inventories list is automatically truncated to ensure valid JSON is returned.

• An explicitly passed limit will not be overridden

• When truncation occurs, the response includes a _truncation field, suggesting using limit/start for pagination or fields to reduce returned fields

Usage

Run as an MCP Server

# 使用 uvx 直接运行（无需安装）
uvx zsvirt-mcp-server

# 或使用 pipx
pipx run zsvirt-mcp-server

# 如果已安装，直接运行
zsvirt-mcp-server

Run in SSE Mode

stdio transport is used by default. To use SSE mode, switch via command line or environment variables:

# 命令行方式
uvx zsvirt-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 zsvirt-mcp-server

Note: Also compatible with FASTMCP_HOST / FASTMCP_PORT / FASTMCP_MOUNT_PATH (FastMCP native environment variables)

Run in Streamable HTTP Mode

# 命令行方式
uvx zsvirt-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 zsvirt-mcp-server

Note: Also compatible with FASTMCP_STREAMABLE_HTTP_PATH

HTTP Header Authentication (Multi-Tenant Mode)

In SSE or streamable-http mode, an administrator can start a shared MCP Server, and multiple users can pass their own credentials via HTTP headers to achieve multi-tenant isolation.

Supported HTTP headers:

Credential priority: HTTP headers > environment variables

Typical usage:

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

Users can use their own accounts by adding HTTP headers in the MCP client configuration:

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

Features:

• Sessions for the same account are automatically cached and reused; a new Session is not created for every request

• Requests with different X-ZStack-API-URL values are routed to different ZStack environments

• In stdio mode there are no HTTP headers, so it automatically falls back to environment variable authentication, with unchanged behavior

Configure in Claude Desktop

Add the following to claude_desktop_config.json:

Option 1: Use username/password

{
  "mcpServers": {
    "zstack": {
      "command": "uvx",
      "args": ["zsvirt-mcp-server"],
      "env": {
        "ZSTACK_API_URL": "http://your-zstack-server:8080",
        "ZSTACK_ACCOUNT": "admin",
        "ZSTACK_PASSWORD": "your-password",
        "ZSTACK_ALLOW_ALL_API": "false"
      }
    }
  }
}

Option 2: Use Session ID

{
  "mcpServers": {
    "zstack": {
      "command": "uvx",
      "args": ["zsvirt-mcp-server"],
      "env": {
        "ZSTACK_API_URL": "http://your-zstack-server:8080",
        "ZSTACK_SESSION_ID": "your-session-uuid",
        "ZSTACK_ALLOW_ALL_API": "false"
      }
    }
  }
}

💡 Set ZSTACK_ALLOW_ALL_API to "true" to enable write operations (create/delete/modify, etc.)

Available Tools

1. search_api

Search ZStack APIs by keyword.

Parameters:

• keywords (list[str]): Search keywords, e.g., ["Query", "Vm"]

• category (str, optional): Filter by category

• limit (int, default 15): Maximum number of results

2. describe_api

Get detailed parameter descriptions for a specified API.

Parameters:

• api_name (str): API name, e.g., "QueryVmInstance"

3. execute_api

Execute a ZStack API.

Parameters:

• api_name (str): API name

• parameters (dict): API parameters

4. search_metric

Search available monitoring metrics.

Parameters:

• keywords (list[str]): Search keywords

• namespace (str, optional): Filter by namespace (supports fuzzy matching, e.g., vm/host)

• limit (int, default 20): Maximum number of results

• match_mode (str, default or): Keyword matching mode (and/or)

• prefer_namespaces (list[str], optional): List of namespaces to prioritize in sorting (default ["ZStack/VM","ZStack/Host"])

💡 Tip: If you are unsure about the namespace, you can omit it for now; the returned results will include namespace values for you to choose from. 💡 The default match_mode=or (union of multiple keywords); for intersection, explicitly pass and. 💡 Metric names may be duplicated across namespaces; it is recommended to specify namespace or prefer_namespaces to ensure sorting priority.

5. get_metric_data

Get monitoring data.

Parameters:

• namespace (str): Namespace

• metric_name (str): Metric name

• start_time (str|int, optional): Start time (ISO or Unix timestamp in seconds)

• end_time (str|int, optional): End time (ISO or Unix timestamp in seconds)

• period (int, default 60): Sampling period (seconds)

• labels (list[str]|dict, optional): Label filter, e.g., ["VMUuid=xxx"] or {"VMUuid":"xxx"}

• summary_only (bool, optional): Return only summary statistics (point count/max/min/avg/variance/stddev)

Data Volume Notes:

• Estimated returned data points: ceil((end_time - start_time) / period) * series_count

• series_count is the number of distinct label combinations; multiple series may be returned if labels is not provided

• It is recommended to shorten the time range, increase period, or add labels filters to avoid overly large output

6. get_metric_summary

Get aggregated TopN of monitoring metrics (grouped by label_key).

Parameters:

• namespace (str): Namespace

• metric_name (str): Metric name

• label_key (str): Label key, e.g., VMUuid/HostUuid

• metric_names (list[str], optional): Combine multiple metrics (e.g., in/out)

• start_time (str|int, optional): Start time (ISO or Unix timestamp in seconds)

• end_time (str|int, optional): End time (ISO or Unix timestamp in seconds)

• period (int, default 60): Sampling period (seconds)

• aggregate (str, default max): Aggregation method for a single metric (max/avg/sum/min)

• combine (str, default sum): Combination method for multiple metrics (sum/avg/max/min)

• threshold_op (str, optional): Threshold comparison operator (>,>=,<,<=,==,!=)

• threshold_value (number, optional): Threshold value

• top_n (int, default 10): Number of results to return

• resolve_resource (str, optional): vm or host, used to resolve names

Query API Condition Syntax

For Query-type APIs, the conditions parameter supports the following operators:

conditions format:

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

Example Interaction

User asks: "Help me look up the details of the VM whose UUID starts with ae6e57a0"

The AI will:

1. Call search_api(keywords=["Query", "Vm", "Instance"])

2. Call describe_api(api_name="QueryVmInstance")

3. Call execute_api(api_name="QueryVmInstance", parameters={"conditions": [{"name": "uuid", "op": "?=", "value": "ae6e57a0%"}]})

Development

# 克隆仓库
git clone https://github.com/ZSvirt/zsvirt-mcp-server/zsvirt-mcp-server.git
cd zsvirt-mcp-server

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

# 运行测试
pytest

License

MIT