ZSvirt MCP Server

AI가 ZSvirt의 2000+ API를 동적으로 조회하고 호출할 수 있게 해주는 MCP Server입니다.

기능 특징

• API 검색: 키워드로 ZStack API를 검색, 퍼지 매칭 지원

• API 설명: API의 상세 파라미터 설명 획득

• API 실행: ZStack API를 실행하고 결과 반환

• 모니터링 지표 검색: 사용 가능한 모니터링 지표 검색

• 모니터링 데이터 조회: 지정된 지표의 모니터링 데이터 획득

설치

# 从 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* - 카운트류

• 기타 읽기 전용 작업...

쓰기 작업 API(예: CreateVmInstance, DeleteVolume 등)를 호출하려면 다음을 설정해야 합니다:

export ZSTACK_ALLOW_ALL_API="true"

⚠️ 경고: 쓰기 작업을 활성화하면 AI가 생성, 삭제, 수정 등의 위험한 작업을 수행할 수 있으므로 주의해서 사용하세요!

쿼리 응답 제어

Query API는 기본적으로 limit=50이 주입되어 한 번에 전체 데이터를 가져와 모델 컨텍스트 창을 가득 채우는 것을 방지합니다. 응답이 64KB를 초과하면 inventories 목록이 자동으로 잘려 유효한 JSON을 반환합니다.

• 명시적으로 limit를 전달하면 덮어쓰지 않습니다

• 잘림이 발생하면 응답에 _truncation 필드가 포함되어 limit/start로 페이지를 넘기거나 fields로 반환 필드를 줄이도록 안내합니다

사용 방법

MCP Server로 실행

# 使用 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 Server를 시작하고 여러 사용자가 HTTP 헤더를 통해 각자의 자격 증명을 전달하여 멀티 테넌트 격리를 구현할 수 있습니다.

지원되는 HTTP 헤더:

자격 증명 우선순위: HTTP 헤더 > 환경 변수

일반적인 사용 예:

# 管理员启动共享 MCP Server
ZSTACK_ALLOW_ALL_API=false uvx zsvirt-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에 다음을 추가합니다:

방법 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

키워드로 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 파라미터는 다음 연산자를 지원합니다:

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

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

# 运行测试
pytest

License

MIT