ZSvirt MCP Server

Ein MCP-Server, der es KI ermöglicht, dynamisch auf über 2000+ APIs von ZSvirt zuzugreifen und diese aufzurufen.

Funktionen

• API-Suche: Durchsucht ZStack-APIs nach Schlüsselwörtern, unterstützt unscharfe Übereinstimmung

• API-Beschreibung: Ruft detaillierte Parameterbeschreibungen für APIs ab

• API-Ausführung: Führt ZStack-APIs aus und gibt Ergebnisse zurück

• Metrik-Suche: Durchsucht verfügbare Überwachungsmetriken

• Metrik-Datenabruf: Ruft Überwachungsdaten für angegebene Metriken ab

Installation

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

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

💡 Sie können es auch ohne Installation direkt mit uvx oder pipx run ausführen (siehe Verwendung unten)

Konfiguration

Legen Sie die folgenden Umgebungsvariablen fest:

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

Authentifizierungsmethoden

💡 Wenn sowohl ZSTACK_SESSION_ID als auch Benutzername/Passwort festgelegt sind, wird die Session-ID bevorzugt verwendet

Sicherheitshinweis

Standardmäßig sind nur schreibgeschützte APIs erlaubt, einschließlich:

• Query* - Abfrageklasse

• Get* - Abrufklasse

• List* - Listenklasse

• Describe* - Beschreibungsklasse

• Check* - Prüfklasse

• Count* - Zählklasse

• Andere schreibgeschützte Operationen...

Um Schreiboperationen (z. B. CreateVmInstance, DeleteVolume usw.) aufzurufen, müssen Sie Folgendes festlegen:

export ZSTACK_ALLOW_ALL_API="true"

⚠️ Warnung: Nach Aktivierung von Schreiboperationen kann die KI gefährliche Aktionen wie Erstellen, Löschen und Ändern ausführen. Bitte vorsichtig verwenden!

Steuerung der Abfrageantworten

Query-APIs injizieren standardmäßig limit=50, um zu verhindern, dass das Abrufen aller Daten das Modellkontextfenster überlastet. Antworten über 64KB werden automatisch in der Inventarliste gekürzt, um gültiges JSON zu gewährleisten.

• Ein explizit übergebenes limit wird nicht überschrieben

• Bei Kürzung enthält die Antwort das Feld _truncation, das auf die Verwendung von limit/start für die Paginierung oder fields zur Reduzierung der zurückgegebenen Felder hinweist

Verwendung

Als MCP-Server ausführen

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

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

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

SSE-Modus

Standardmäßig wird stdio-Transport verwendet. Für den SSE-Modus können Sie über die Befehlszeile oder Umgebungsvariablen wechseln:

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

Hinweis: Kompatibel mit FASTMCP_HOST / FASTMCP_PORT / FASTMCP_MOUNT_PATH (native FastMCP-Umgebungsvariablen)

Streamable-HTTP-Modus

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

Hinweis: Kompatibel mit FASTMCP_STREAMABLE_HTTP_PATH

HTTP-Header-Authentifizierung (Multi-Tenant-Modus)

Im SSE- oder streamable-http-Modus kann ein Administrator einen gemeinsamen MCP-Server starten, und mehrere Benutzer übergeben ihre eigenen Anmeldeinformationen über HTTP-Header, um eine Mandantentrennung zu erreichen.

Unterstützte HTTP-Header:

Priorität der Anmeldeinformationen: HTTP-Header > Umgebungsvariablen

Typische Verwendung:

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

Benutzer können ihre eigenen Konten verwenden, indem sie HTTP-Header in der MCP-Client-Konfiguration hinzufügen:

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

Eigenschaften:

• Sessions desselben Kontos werden automatisch zwischengespeichert und wiederverwendet, es wird nicht bei jeder Anfrage eine neue Session erstellt

• Anfragen mit unterschiedlichen X-ZStack-API-URL werden an verschiedene ZStack-Umgebungen weitergeleitet

• Im stdio-Modus gibt es keine HTTP-Header, es wird automatisch auf die Umgebungsvariablen-Authentifizierung zurückgegriffen, das Verhalten bleibt unverändert

Konfiguration in Claude Desktop

Fügen Sie in claude_desktop_config.json Folgendes hinzu:

Methode 1: Benutzername/Passwort verwenden

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

Methode 2: Session-ID verwenden

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

💡 Setzen Sie ZSTACK_ALLOW_ALL_API auf "true", um Schreiboperationen (Erstellen/Löschen/Ändern usw.) zu aktivieren

Verfügbare Werkzeuge

1. search_api

Durchsucht ZStack-APIs nach Schlüsselwörtern.

Parameter:

• keywords (list[str]): Suchschlüsselwörter, z. B. ["Query", "Vm"]

• category (str, optional): Nach Kategorie filtern

• limit (int, Standard 15): Maximale Anzahl der zurückgegebenen Ergebnisse

2. describe_api

Ruft die detaillierte Parameterbeschreibung einer bestimmten API ab.

Parameter:

• api_name (str): API-Name, z. B. "QueryVmInstance"

3. execute_api

Führt eine ZStack-API aus.

Parameter:

• api_name (str): API-Name

• parameters (dict): API-Parameter

4. search_metric

Durchsucht verfügbare Überwachungsmetriken.

Parameter:

• keywords (list[str]): Suchschlüsselwörter

• namespace (str, optional): Nach Namespace filtern (unterstützt unscharfe Übereinstimmung, z. B. vm/host)

• limit (int, Standard 20): Maximale Anzahl der zurückgegebenen Ergebnisse

• match_mode (str, Standard or): Schlüsselwort-Übereinstimmungsmodus (and/or)

• prefer_namespaces (list[str], optional): Bevorzugte Namespace-Liste für die Sortierung (Standard ["ZStack/VM","ZStack/Host"])

💡 Tipp: Wenn Sie sich über den Namespace nicht sicher sind, können Sie ihn zunächst weglassen. Die zurückgegebenen Ergebnisse enthalten den Namespace-Wert zur Auswahl 💡 Standard match_mode=or (ODER-Verknüpfung mehrerer Schlüsselwörter); für UND-Verknüpfung übergeben Sie explizit and 💡 Metriknamen können in verschiedenen Namespaces doppelt vorkommen. Es wird empfohlen, namespace oder prefer_namespaces anzugeben, um eine korrekte Sortierung sicherzustellen

5. get_metric_data

Ruft Überwachungsdaten ab.

Parameter:

• namespace (str): Namespace

• metric_name (str): Metrikname

• start_time (str|int, optional): Startzeit (ISO oder Sekunden-Timestamp)

• end_time (str|int, optional): Endzeit (ISO oder Sekunden-Timestamp)

• period (int, Standard 60): Abtastintervall (Sekunden)

• labels (list[str]|dict, optional): Label-Filter, z. B. ["VMUuid=xxx"] oder {"VMUuid":"xxx"}

• summary_only (bool, optional): Nur Zusammenfassung zurückgeben (Punktanzahl/Maximum/Minimum/Durchschnitt/Varianz/Standardabweichung)

Datenmengen-Hinweis:

• Geschätzte Punktanzahl: ceil((end_time - start_time) / period) * series_count

• series_count ist die Anzahl der verschiedenen Label-Kombinationen; ohne labels können mehrere Serien zurückgegeben werden

• Es wird empfohlen, den Zeitraum zu verkürzen, period zu vergrößern oder labels zur Filterung hinzuzufügen, um zu große Ausgaben zu vermeiden

6. get_metric_summary

Ruft die aggregierten TopN-Werte einer Überwachungsmetrik ab (gruppiert nach label_key).

Parameter:

• namespace (str): Namespace

• metric_name (str): Metrikname

• label_key (str): Label-Schlüssel, z. B. VMUuid/HostUuid

• metric_names (list[str], optional): Zusammenführung mehrerer Metriken (z. B. ein/aus)

• start_time (str|int, optional): Startzeit (ISO oder Sekunden-Timestamp)

• end_time (str|int, optional): Endzeit (ISO oder Sekunden-Timestamp)

• period (int, Standard 60): Abtastintervall (Sekunden)

• aggregate (str, Standard max): Aggregationsmethode für einzelne Metriken (max/avg/sum/min)

• combine (str, Standard sum): Zusammenführungsmethode für mehrere Metriken (sum/avg/max/min)

• threshold_op (str, optional): Schwellwert-Vergleichsoperator (>,>=,<,<=,==,!=)

• threshold_value (number, optional): Schwellwert

• top_n (int, Standard 10): Anzahl der zurückzugebenden Einträge

• resolve_resource (str, optional): vm oder host, zur Auflösung von Namen

Syntax für Query-API-Bedingungen

Für Query-APIs unterstützt der Parameter conditions die folgenden Operatoren:

Format von conditions:

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

Beispielinteraktion

Benutzer fragt: "Kannst du mir die Details der VM abrufen, deren UUID mit ae6e57a0 beginnt?"

Die KI wird:

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

2. describe_api(api_name="QueryVmInstance") aufrufen

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

Entwicklung

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

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

# 运行测试
pytest

Lizenz

MIT