# pixverseai/pixverse-mcp architecture

> Architecture diagram of the GitHub repository pixverseai/pixverse-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pixverseai/pixverse-mcp
- Repository: https://github.com/pixverseai/pixverse-mcp

## Overview

PixVerse MCP exposes video-generation tools to MCP clients, then routes requests through server orchestration and typed request models to a PixVerse API client. The client handles HTTP transport, uploads and generation/status operations; responses return through the server to the assistant. Major capabilities include text/image generation, extensions, transitions, lip sync, sound effects, fusion, and media uploads. The repository also offers an SSE/HTTP interface. Some feature handlers are documented in README or unsampled server sections, so those capability links are documented rather than claims about individual handler internals.

Main entry points: [`src/client/pixverse.py`](https://github.com/pixverseai/pixverse-mcp/blob/main/src/client/pixverse.py) (PixVerse client), [`src/server.py`](https://github.com/pixverseai/pixverse-mcp/blob/main/src/server.py) (Tool dispatch), [`src/client/base.py`](https://github.com/pixverseai/pixverse-mcp/blob/main/src/client/base.py) (HTTP transport), [`src/sse_server.py`](https://github.com/pixverseai/pixverse-mcp/blob/main/src/sse_server.py) (SSE HTTP interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Client interfaces"]
  node_mcp_server["MCP server<br/>[server.py]"]
  node_sse_http["SSE HTTP interface<br/>[sse_server.py]"]
end

subgraph group_orchestration["Tool orchestration"]
  node_configuration["Configuration<br/>[config.py]"]
  node_request_handling["Tool dispatch<br/>[server.py]"]
  node_api_errors["API errors<br/>[exceptions.py]"]
end

subgraph group_generation["Generation and API"]
  node_api_client["PixVerse client<br/>[pixverse.py]"]
  node_http_transport["HTTP transport<br/>[base.py]"]
end

subgraph group_contracts["Models and validation"]
  node_request_models["Generation requests<br/>[requests.py]"]
  node_common_types["Shared types<br/>[common.py]"]
  node_response_models["API responses<br/>[responses.py]"]
  node_validation["Parameter validation<br/>[validation.py]"]
end

node_mcp_user(("MCP client"))
node_pixverse_api{{"PixVerse API"}}

node_mcp_user -->|"invokes tools"| node_mcp_server
node_mcp_server -->|"loads settings"| node_configuration
node_mcp_server -->|"registers handlers"| node_request_handling
node_request_handling -->|"dispatches generation"| node_api_client
node_request_handling -->|"uses requests"| node_request_models
node_request_handling -->|"formats results"| node_response_models
node_api_client -->|"inherits transport"| node_http_transport
node_api_client -->|"accepts requests"| node_request_models
node_api_client -->|"returns responses"| node_response_models
node_api_client -->|"sends API calls"| node_http_transport
node_http_transport -->|"makes HTTP requests"| node_pixverse_api
node_http_transport -->|"raises API errors"| node_api_errors
node_api_client -->|"raises validation errors"| node_api_errors
node_request_models -->|"uses shared types"| node_common_types
node_validation -->|"checks constraints"| node_common_types
node_validation -->|"raises validation errors"| node_api_errors
node_mcp_user -.->|"uses HTTP endpoints"| node_sse_http
node_sse_http -->|"calls MCP tools"| node_mcp_server
node_sse_http -->|"checks video status"| node_api_client
node_api_client -.->|"supports generation and uploads"| node_pixverse_api

click node_mcp_server "https://github.com/pixverseai/pixverse-mcp/blob/main/src/server.py"
click node_sse_http "https://github.com/pixverseai/pixverse-mcp/blob/main/src/sse_server.py"
click node_configuration "https://github.com/pixverseai/pixverse-mcp/blob/main/src/config.py"
click node_request_handling "https://github.com/pixverseai/pixverse-mcp/blob/main/src/server.py"
click node_api_client "https://github.com/pixverseai/pixverse-mcp/blob/main/src/client/pixverse.py"
click node_http_transport "https://github.com/pixverseai/pixverse-mcp/blob/main/src/client/base.py"
click node_api_errors "https://github.com/pixverseai/pixverse-mcp/blob/main/src/exceptions.py"
click node_request_models "https://github.com/pixverseai/pixverse-mcp/blob/main/src/models/requests.py"
click node_common_types "https://github.com/pixverseai/pixverse-mcp/blob/main/src/models/common.py"
click node_response_models "https://github.com/pixverseai/pixverse-mcp/blob/main/src/models/responses.py"
click node_validation "https://github.com/pixverseai/pixverse-mcp/blob/main/src/utils/validation.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp_server,node_sse_http,node_mcp_user toneBlue
class node_configuration,node_request_handling,node_api_errors toneAmber
class node_api_client,node_http_transport,node_pixverse_api toneMint
class node_request_models,node_common_types,node_response_models,node_validation toneRose
```

## Components

### Client interfaces

- [MCP server](https://github.com/pixverseai/pixverse-mcp/blob/main/src/server.py): `src/server.py`
- [SSE HTTP interface](https://github.com/pixverseai/pixverse-mcp/blob/main/src/sse_server.py): `src/sse_server.py`

### Tool orchestration

- [Configuration](https://github.com/pixverseai/pixverse-mcp/blob/main/src/config.py): `src/config.py`
- [Tool dispatch](https://github.com/pixverseai/pixverse-mcp/blob/main/src/server.py): `src/server.py`
- [API errors](https://github.com/pixverseai/pixverse-mcp/blob/main/src/exceptions.py): `src/exceptions.py`

### Generation and API

- [PixVerse client](https://github.com/pixverseai/pixverse-mcp/blob/main/src/client/pixverse.py): `src/client/pixverse.py`
- [HTTP transport](https://github.com/pixverseai/pixverse-mcp/blob/main/src/client/base.py): `src/client/base.py`

### Models and validation

- [Generation requests](https://github.com/pixverseai/pixverse-mcp/blob/main/src/models/requests.py): `src/models/requests.py`
- [Shared types](https://github.com/pixverseai/pixverse-mcp/blob/main/src/models/common.py): `src/models/common.py`
- [API responses](https://github.com/pixverseai/pixverse-mcp/blob/main/src/models/responses.py): `src/models/responses.py`
- [Parameter validation](https://github.com/pixverseai/pixverse-mcp/blob/main/src/utils/validation.py): `src/utils/validation.py`

### Other components

- **MCP client**
- **PixVerse API**

## Connections

- MCP client → MCP server: invokes tools (evidence: `README.md`)
- MCP server → Configuration: loads settings (evidence: `src/server.py`)
- MCP server → Tool dispatch: registers handlers (evidence: `src/server.py`)
- Tool dispatch → PixVerse client: dispatches generation (evidence: `src/server.py`)
- Tool dispatch → Generation requests: uses requests (evidence: `src/server.py`)
- Tool dispatch → API responses: formats results (evidence: `src/server.py`)
- PixVerse client → HTTP transport: inherits transport (evidence: `src/client/pixverse.py`)
- PixVerse client → Generation requests: accepts requests (evidence: `src/client/pixverse.py`)
- PixVerse client → API responses: returns responses (evidence: `src/client/pixverse.py`)
- PixVerse client → HTTP transport: sends API calls (evidence: `src/client/pixverse.py`)
- HTTP transport → PixVerse API: makes HTTP requests (evidence: `src/client/base.py`)
- HTTP transport → API errors: raises API errors (evidence: `src/client/base.py`)
- PixVerse client → API errors: raises validation errors (evidence: `src/client/pixverse.py`)
- Generation requests → Shared types: uses shared types (evidence: `src/models/requests.py`)
- Parameter validation → Shared types: checks constraints (evidence: `src/utils/validation.py`)
- Parameter validation → API errors: raises validation errors (evidence: `src/utils/validation.py`)
- MCP client → SSE HTTP interface: uses HTTP endpoints (evidence: `src/sse_server.py`)
- SSE HTTP interface → MCP server: calls MCP tools (evidence: `src/sse_server.py`)
- SSE HTTP interface → PixVerse client: checks video status (evidence: `src/sse_server.py`)
- PixVerse client → PixVerse API: supports generation and uploads (evidence: `README.md`)
