ZSvirt MCP Server

Un servidor MCP que permite a la IA consultar e invocar dinámicamente las más de 2000 API de ZSvirt.

Características

• Búsqueda de API: Busca API de ZStack por palabras clave, con soporte de coincidencia difusa

• Descripción de API: Obtiene la descripción detallada de los parámetros de una API

• Ejecución de API: Ejecuta API de ZStack y devuelve los resultados

• Búsqueda de métricas de monitoreo: Busca métricas de monitoreo disponibles

• Obtención de datos de monitoreo: Obtiene los datos de monitoreo de una métrica específica

Instalación

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

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

💡 También puedes omitir la instalación y ejecutarlo directamente con uvx o pipx run (consulta la sección de uso a continuación)

Configuración

Configura las siguientes variables de entorno:

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

Explicación de los métodos de autenticación

💡 Si se configuran tanto ZSTACK_SESSION_ID como usuario y contraseña, se usará el Session ID con prioridad

Nota de seguridad

De forma predeterminada, solo se permiten llamar a API de solo lectura, incluyendo:

• Query* - Consultas

• Get* - Obtención

• List* - Listados

• Describe* - Descripciones

• Check* - Verificaciones

• Count* - Conteos

• Otras operaciones de solo lectura...

Para invocar API de escritura (como CreateVmInstance, DeleteVolume, etc.), es necesario configurar:

export ZSTACK_ALLOW_ALL_API="true"

⚠️ Advertencia: Al habilitar operaciones de escritura, la IA puede ejecutar operaciones peligrosas como crear, eliminar o modificar. ¡Úsalo con precaución!

Control de respuesta de consultas

Las API Query inyectan limit=50 de forma predeterminada para evitar que la descarga completa de datos sature la ventana de contexto del modelo. Cuando la respuesta supera los 64KB, la lista de inventories se recorta automáticamente para garantizar que se devuelva JSON válido.

• Si se pasa limit explícitamente, no se sobrescribe

• Cuando se produce el recorte, la respuesta incluye el campo _truncation, que sugiere usar limit/start para paginar o fields para reducir los campos devueltos

Formas de uso

Ejecutar como servidor MCP

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

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

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

Ejecutar en modo SSE

De forma predeterminada se usa transporte stdio. Si necesitas el modo SSE, puedes cambiarlo mediante la línea de comandos o variables de entorno:

# 命令行方式
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

Nota: También es compatible con FASTMCP_HOST / FASTMCP_PORT / FASTMCP_MOUNT_PATH (variables de entorno nativas de FastMCP)

Ejecutar en modo Streamable HTTP

# 命令行方式
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

Nota: También es compatible con FASTMCP_STREAMABLE_HTTP_PATH

Autenticación por cabeceras HTTP (modo multiinquilino)

En los modos SSE o streamable-http, un administrador puede iniciar un servidor MCP compartido y varios usuarios pueden pasar sus propias credenciales mediante cabeceras HTTP, logrando aislamiento multiinquilino.

Cabeceras HTTP compatibles:

Prioridad de credenciales: Cabeceras HTTP > Variables de entorno

Uso típico:

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

Los usuarios pueden agregar cabeceras HTTP en la configuración de su cliente MCP para usar sus propias cuentas:

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

Características:

• La Session de la misma cuenta se almacena en caché y se reutiliza automáticamente, sin crear una nueva Session en cada solicitud

• Las solicitudes con diferentes X-ZStack-API-URL se enrutan a diferentes entornos de ZStack

• En modo stdio no hay cabeceras HTTP, por lo que se recurre automáticamente a la autenticación por variables de entorno, sin cambios de comportamiento

Configuración en Claude Desktop

Agrega lo siguiente en claude_desktop_config.json:

Opción 1: Usar usuario y contraseña

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

Opción 2: Usar 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"
      }
    }
  }
}

💡 Configura ZSTACK_ALLOW_ALL_API en "true" para habilitar operaciones de escritura (crear/eliminar/modificar, etc.)

Herramientas disponibles

1. search_api

Busca API de ZStack por palabras clave.

Parámetros:

• keywords (list[str]): Palabras clave de búsqueda, por ejemplo ["Query", "Vm"]

• category (str, opcional): Filtro por categoría

• limit (int, predeterminado 15): Cantidad máxima de resultados

2. describe_api

Obtiene la descripción detallada de los parámetros de una API específica.

Parámetros:

• api_name (str): Nombre de la API, por ejemplo "QueryVmInstance"

3. execute_api

Ejecuta una API de ZStack.

Parámetros:

• api_name (str): Nombre de la API

• parameters (dict): Parámetros de la API

4. search_metric

Busca métricas de monitoreo disponibles.

Parámetros:

• keywords (list[str]): Palabras clave de búsqueda

• namespace (str, opcional): Filtro por espacio de nombres (admite coincidencia difusa, por ejemplo vm/host)

• limit (int, predeterminado 20): Cantidad máxima de resultados

• match_mode (str, predeterminado or): Modo de coincidencia de palabras clave (and/or)

• prefer_namespaces (list[str], opcional): Lista de espacios de nombres con prioridad de ordenación (predeterminado ["ZStack/VM","ZStack/Host"])

💡 Sugerencia: Si no estás seguro del namespace, puedes omitirlo; los resultados devueltos incluirán el valor del namespace para que elijas 💡 El valor predeterminado de match_mode=or (unión de múltiples palabras clave); para intersección, pasa explícitamente and 💡 Los nombres de métricas pueden repetirse en diferentes namespaces; se recomienda especificar namespace o prefer_namespaces para garantizar la prioridad de ordenación

5. get_metric_data

Obtiene datos de monitoreo.

Parámetros:

• namespace (str): Espacio de nombres

• metric_name (str): Nombre de la métrica

• start_time (str|int, opcional): Hora de inicio (ISO o timestamp en segundos)

• end_time (str|int, opcional): Hora de fin (ISO o timestamp en segundos)

• period (int, predeterminado 60): Período de muestreo (segundos)

• labels (list[str]|dict, opcional): Filtro de etiquetas, por ejemplo ["VMUuid=xxx"] o {"VMUuid":"xxx"}

• summary_only (bool, opcional): Devuelve solo información estadística (número de puntos/máximo/mínimo/promedio/varianza/desviación estándar)

Nota sobre el volumen de datos:

• Estimación de puntos devueltos: ceil((end_time - start_time) / period) * series_count

• series_count es el número de combinaciones de etiquetas diferentes; si no se pasan labels, pueden devolverse múltiples series

• Se recomienda acortar el rango de tiempo, aumentar period o agregar filtros labels para evitar salidas demasiado grandes

6. get_metric_summary

Obtiene el TopN agregado de métricas de monitoreo (agrupado por label_key).

Parámetros:

• namespace (str): Espacio de nombres

• metric_name (str): Nombre de la métrica

• label_key (str): Clave de etiqueta, por ejemplo VMUuid/HostUuid

• metric_names (list[str], opcional): Combinación de múltiples métricas (por ejemplo in/out)

• start_time (str|int, opcional): Hora de inicio (ISO o timestamp en segundos)

• end_time (str|int, opcional): Hora de fin (ISO o timestamp en segundos)

• period (int, predeterminado 60): Período de muestreo (segundos)

• aggregate (str, predeterminado max): Método de agregación de métrica individual (max/avg/sum/min)

• combine (str, predeterminado sum): Método de combinación de múltiples métricas (sum/avg/max/min)

• threshold_op (str, opcional): Operador de comparación de umbral (>,>=,<,<=,==,!=)

• threshold_value (number, opcional): Valor del umbral

• top_n (int, predeterminado 10): Número de resultados

• resolve_resource (str, opcional): vm o host, para resolver nombres

Sintaxis de condiciones para API Query

Para las API de tipo Query, el parámetro conditions admite los siguientes operadores:

Formato de conditions:

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

Ejemplo de interacción

El usuario pregunta: "Ayúdame a consultar los detalles de la VM cuyo UUID comienza con ae6e57a0"

La IA hará:

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

2. Llamar a describe_api(api_name="QueryVmInstance")

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

Desarrollo

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

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

# 运行测试
pytest

Licencia

MIT