ZSvirt MCP Server

MCP-сервер, позволяющий ИИ динамически запрашивать и вызывать 2000+ API ZSvirt.

Возможности

• Поиск API: поиск API ZStack по ключевым словам с поддержкой нечёткого сопоставления

• Описание API: получение подробного описания параметров API

• Выполнение API: выполнение API ZStack и возврат результата

• Поиск метрик мониторинга: поиск доступных метрик мониторинга

• Получение данных мониторинга: получение данных мониторинга по указанным метрикам

Установка

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

# 或者使用 uv
uv pip install zsvirt-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_SESSION_ID, и имя пользователя с паролем, приоритет отдаётся Session ID

Примечание по безопасности

По умолчанию разрешены только API на чтение, включая:

• Query* — запросы

• Get* — получение

• List* — списки

• Describe* — описания

• Check* — проверки

• Count* — подсчёт

• Прочие операции только на чтение...

Для вызова операций записи (например, CreateVmInstance, DeleteVolume и т.д.) необходимо задать:

export ZSTACK_ALLOW_ALL_API="true"

⚠️ Предупреждение: после включения операций записи ИИ сможет выполнять опасные действия — создание, удаление, изменение. Используйте с осторожностью!

Управление размером ответов Query

В Query API по умолчанию подставляется limit=50, чтобы предотвратить переполнение контекстного окна модели при полной выгрузке данных. Если ответ превышает 64 КБ, список inventories автоматически обрезается для сохранения корректного JSON.

• Явно переданный limit не перезаписывается

• При обрезке в ответ добавляется поле _truncation, подсказывающее использовать limit/start для постраничной навигации или fields для сокращения возвращаемых полей

Способы использования

Запуск в качестве MCP-сервера

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

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

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

Запуск в режиме SSE

По умолчанию используется транспорт stdio. Для режима SSE можно переключиться через аргументы командной строки или переменные окружения:

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

Примечание: также поддерживаются FASTMCP_HOST / FASTMCP_PORT / FASTMCP_MOUNT_PATH (нативные переменные окружения FastMCP)

Запуск в режиме 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

Примечание: также поддерживается FASTMCP_STREAMABLE_HTTP_PATH

Аутентификация через HTTP-заголовки (режим мультитенантности)

В режимах SSE или streamable-http администратор может запустить общий MCP-сервер, а несколько пользователей передают свои учётные данные через HTTP-заголовки, обеспечивая изоляцию между арендаторами.

Поддерживаемые HTTP-заголовки:

Приоритет учётных данных: HTTP-заголовки > переменные окружения

Типичное применение:

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

Пользователь добавляет HTTP-заголовки в конфигурацию MCP-клиента и использует свою учётную запись:

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

Способ 1: имя пользователя и пароль

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

Способ 2: 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"
      }
    }
  }
}

💡 Установите ZSTACK_ALLOW_ALL_API в "true", чтобы включить операции записи (создание/удаление/изменение и т.д.)

Доступные инструменты

1. search_api

Поиск API ZStack по ключевым словам.

Параметры:

• keywords (list[str]): ключевые слова для поиска, например ["Query", "Vm"]

• category (str, необязательно): фильтр по категории

• limit (int, по умолчанию 15): максимальное количество возвращаемых результатов

2. describe_api

Получение подробного описания параметров указанного API.

Параметры:

• api_name (str): имя API, например "QueryVmInstance"

3. execute_api

Выполнение API ZStack.

Параметры:

• 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 или 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 — количество различных комбинаций меток; если 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

Для API класса Query параметр conditions поддерживает следующие операторы:

Формат conditions:

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

Пример взаимодействия

Пользователь спрашивает: «Помоги мне получить детали VM, UUID которой начинается с ae6e57a0»

ИИ выполнит:

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/ZSvirt/zsvirt-mcp-server/zsvirt-mcp-server.git
cd zsvirt-mcp-server

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

# 运行测试
pytest

Лицензия

MIT