# Z.AI Image & Video Generation MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides access to Z.AI's image and video generation models for LLM applications.

## Features

- **Image Generation**: GLM-Image and CogView-4 models for high-quality image generation
- **Video Generation**: CogVideoX-3, Vidu Q1, and Vidu 2 models for AI video creation
- **Multiple Input Modes**: Text-to-image/video, image-to-video, start-end frame animation
- **Asynchronous Processing**: Submit long-running tasks and poll for results
- **Automatic Downloads**: Generate and download in a single operation
- **Automatic Retries**: Built-in retry logic with exponential backoff
- **Comprehensive Validation**: Input validation with clear error messages
- **Type-Safe**: Full TypeScript support with detailed type definitions

## Installation

```bash
npm install z-ai-image-mcp
```

## Configuration

Set your Z.AI API key as an environment variable:

```bash
export ZAI_API_KEY=your_api_key_here
```

Get your API key from the [Z.AI API Keys page](https://z.ai/manage-apikey/apikey-list) or sign up for the [GLM Coding Plan](https://z.ai/subscribe?ic=E7H8IV5TXG).

### Optional Configuration

| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `ZAI_API_BASE_URL` | API base URL | `https://api.z.ai/api` |
| `ZAI_DEFAULT_MODEL` | Default model | `glm-image` |
| `ZAI_DEFAULT_SIZE` | Default image size | `1280x1280` |
| `ZAI_REQUEST_TIMEOUT` | Request timeout (ms) | `60000` |
| `ZAI_MAX_RETRIES` | Max retry attempts | `3` |
| `ZAI_RETRY_DELAY` | Initial retry delay (ms) | `1000` |

## Usage

### With Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "z-ai-image": {
      "command": "npx",
      "args": ["z-ai-image-mcp"],
      "env": {
        "ZAI_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### With Other MCP Clients

Run the server directly:

```bash
npx z-ai-image-mcp
```

Or programmatically:

```typescript
import { createServer, loadConfig } from 'z-ai-image-mcp';

const config = loadConfig();
const server = createServer(config);
// Connect to your transport...
```

### With OpenCode

Add to your OpenCode configuration (`opencode.json` or `opencode.jsonc` in your project root):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "z-ai-image": {
      "type": "local",
      "command": ["npx", "z-ai-image-mcp"],
      "enabled": true,
      "environment": {
        "ZAI_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Or using an environment variable reference:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "z-ai-image": {
      "type": "local",
      "command": ["npx", "z-ai-image-mcp"],
      "enabled": true,
      "environment": {
        "ZAI_API_KEY": "{env:ZAI_API_KEY}"
      }
    }
  }
}
```

**Using with OpenCode prompts:**

```
Generate a professional logo for a tech startup. use z-ai-image
```

Or add to your `AGENTS.md`:

```markdown
When generating images, use the `z-ai-image` MCP server tools.
```

**Per-agent configuration (optional):**

To enable the MCP server only for specific agents:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "z-ai-image": {
      "type": "local",
      "command": ["npx", "z-ai-image-mcp"],
      "enabled": true,
      "environment": {
        "ZAI_API_KEY": "{env:ZAI_API_KEY}"
      }
    }
  },
  "tools": {
    "z-ai-image*": false
  },
  "agent": {
    "design-agent": {
      "tools": {
        "z-ai-image*": true
      }
    }
  }
}
```

## Available Tools

### 1. `list_models`

List all available image generation models and their capabilities.

```
Use this tool to discover available models, their features, and recommended settings.
```

### 2. `generate_image`

Generate an image synchronously from a text prompt.

**Parameters:**
- `prompt` (required): Text description of the image (max 4000 characters)
- `model` (optional): `glm-image` or `cogview-4-250304` (default: `glm-image`)
- `size` (optional): Image dimensions, e.g., `1280x1280` (default: `1280x1280`)
- `quality` (optional): `hd` or `standard` (default: `hd` for GLM-Image)
- `user_id` (optional): End user ID for abuse prevention (6-128 characters)

**Example:**
```
Generate an image of a cute kitten sitting on a windowsill with a sunset background.
```

### 3. `generate_image_async`

Start an asynchronous image generation task. Returns a task ID for polling.

**Parameters:**
- `prompt` (required): Text description of the image
- `model` (optional): Only `glm-image` supports async (default: `glm-image`)
- `size` (optional): Image dimensions (default: `1280x1280`)
- `quality` (optional): Only `hd` supported for async (default: `hd`)
- `user_id` (optional): End user ID for abuse prevention

**Example:**
```
Start async generation of a complex poster design.
```

### 4. `get_async_result`

Retrieve the result of an asynchronous image generation task.

**Parameters:**
- `task_id` (required): The task ID from `generate_image_async`

**Example:**
```
Check the status of task ID "task-12345".
```

### 5. `download_image`

Download an image from a URL and return it as base64 or save to a file.

**Parameters:**
- `url` (required): The URL of the image to download (e.g., from `generate_image` or `get_async_result`)
- `output` (optional): `base64` or `file_output` (default: `base64`)
- `file_output` (optional): Absolute path to save the image file (required if output is `file_output`). Example: `/path/to/image.png`

**Output Modes:**
- `base64`: Returns the image data directly as base64 (auto-switches to file if > 1MB)
- `file_output`: Saves the image to disk at the specified path

**Example:**
```
Download the generated image and save it to /home/user/images/logo.png
```

> **Note:** Z.AI image URLs expire after 30 days. Use this tool to download and store images permanently.

### 6. `generate_and_download_image` ⭐ Recommended

Generate an image and automatically download it in a single operation. This is the most convenient tool when you want the image data immediately.

**Parameters:**
- `prompt` (required): Text description of the image (max 4000 characters)
- `model` (optional): `glm-image` or `cogview-4-250304` (default: `glm-image`)
- `size` (optional): Image dimensions, e.g., `1280x1280` (default: `1280x1280`)
- `quality` (optional): `hd` or `standard` (default: `hd` for GLM-Image)
- `user_id` (optional): End user ID for abuse prevention (6-128 characters)
- `output` (optional): `base64` or `file_output` (default: `base64`)
- `file_output` (optional): Absolute path to save the image file (required if output is `file_output`)
- `poll_interval` (optional): Seconds to wait between polling for async results (default: 3)
- `max_wait` (optional): Maximum seconds to wait for generation (default: 120)

**Output Modes:**
- `base64`: Returns the image data directly as base64 (auto-switches to file if > 1MB)
- `file_output`: Saves the image to disk at the specified path

**Examples:**
```
# Generate and get as base64
Generate a logo for my company and show me the image.

# Generate and save to file
Generate a logo and save it to /home/user/images/logo.png
```

**Behavior:**
- For GLM-Image: Uses async API with automatic polling until complete
- For CogView-4: Uses synchronous API
- Automatically downloads the result once generation completes
- Returns image as base64 or saves to specified path

---

## Video Generation Tools

### 7. `list_video_models`

List all available video generation models and their capabilities.

```
Use this tool to discover available video models, their features, and supported parameters.
```

### 8. `generate_video`

Generate a video asynchronously from text or images. Returns a task ID for polling.

**Parameters:**
- `model` (required): Video generation model
  - `cogvideox-3`: Z.AI flagship model (up to 4K, 5-10s, audio support)
  - `viduq1-text`: Text-to-video, 1080P, 5s
  - `viduq1-image`: Image-to-video, 1080P, 5s
  - `viduq1-start-end`: Start-end frame, 1080P, 5s
  - `vidu2-image`: Image-to-video, 720P, 4s (faster, cheaper)
  - `vidu2-start-end`: Start-end frame, 720P, 4s
  - `vidu2-reference`: Reference-based, 720P, 4s
- `prompt` (optional): Text description (max 512 characters)
- `image_url` (optional): Image URL(s) for image-to-video generation
- `quality` (CogVideoX-3): `quality` or `speed`
- `size` (optional): Video resolution
- `duration` (optional): Video duration in seconds
- `fps` (CogVideoX-3): 30 or 60
- `with_audio` (optional): Generate AI sound effects
- `style` (Vidu Q1 text): `general` or `anime`
- `aspect_ratio` (Vidu Q1/2): `16:9`, `9:16`, or `1:1`
- `movement_amplitude` (Vidu): `auto`, `small`, `medium`, or `large`
- `user_id` (optional): End user ID for abuse prevention

**Examples:**
```
# Text-to-video
Generate a video of a cat playing with a ball.

# Image-to-video
Animate this image: [image_url]

# Start-end frame
Create a smooth transition from [first_frame] to [last_frame].
```

### 9. `get_video_result`

Retrieve the result of an asynchronous video generation task.

**Parameters:**
- `task_id` (required): The task ID from `generate_video`

> **Note:** Video generation typically takes 30 seconds to several minutes depending on duration and quality.

### 10. `generate_and_download_video` ⭐ Recommended

Generate a video and automatically download it. Polls for completion and saves the video file.

**Parameters:**
- All parameters from `generate_video` plus:
- `file_output` (optional): Absolute path to save the video file
- `poll_interval` (optional): Seconds to wait between polling (default: 10)
- `max_wait` (optional): Maximum seconds to wait (default: 300)

**Example:**
```
Generate a video of a sunset over the ocean and save it to /home/user/videos/sunset.mp4
```

> **Note:** Videos are always saved to file (too large for base64). Video URLs expire after 1 day.

## Models

### GLM-Image

Z.AI's flagship image generation model with a hybrid autoregressive + diffusion architecture.

- **Best for**: Complex compositions, text rendering, detailed illustrations, commercial posters
- **Quality options**: `hd` (detailed, ~20s), `standard` (faster, ~5-10s)
- **Size range**: 1024-2048px per dimension (divisible by 32)
- **Recommended sizes**: 1280×1280, 1568×1056, 1056×1568, 1472×1088, 1088×1472, 1728×960, 960×1728
- **Async support**: Yes

### CogView-4-250304

General-purpose image generation with fast text understanding.

- **Best for**: General image generation, quick iterations
- **Quality options**: `hd`, `standard`
- **Size range**: 512-2048px per dimension (divisible by 16)
- **Recommended sizes**: 1024×1024, 768×1344, 864×1152, 1344×768, 1152×864, 1440×720, 720×1440
- **Async support**: No

---

## Video Models

### CogVideoX-3

Z.AI's flagship video generation model with improved frame stability and clarity.

- **Best for**: Text-to-video, image-to-video, start-end frame animation
- **Resolution**: Up to 4K (3840x2160)
- **Duration**: 5 or 10 seconds
- **Features**: Audio generation, 30/60 FPS, quality/speed modes
- **Price**: $0.20/video

### Vidu Q1

High-quality video generation with 1080P output.

| Model | Capability | Duration | Price |
|-------|------------|----------|-------|
| `viduq1-text` | Text-to-video | 5s | $0.40 |
| `viduq1-image` | Image-to-video | 5s | $0.40 |
| `viduq1-start-end` | Start-end frame | 5s | $0.40 |

- **Features**: General/anime styles, motion amplitude control

### Vidu 2

Fast and cost-effective video generation with 720P output.

| Model | Capability | Duration | Price |
|-------|------------|----------|-------|
| `vidu2-image` | Image-to-video | 4s | $0.20 |
| `vidu2-start-end` | Start-end frame | 4s | $0.20 |
| `vidu2-reference` | Reference-based | 4s | $0.40 |

- **Features**: Audio generation, motion amplitude control, multi-image reference

## Error Handling

The server handles various error scenarios:

| Error Type | Description |
|-----------|-------------|
| `AUTH_ERROR` | Invalid or missing API key |
| `RATE_LIMIT` | Too many requests - will auto-retry |
| `VALIDATION_ERROR` | Invalid parameters |
| `SERVER_ERROR` | Z.AI server issues - will auto-retry |
| `NETWORK_ERROR` | Connection issues - will auto-retry |
| `TIMEOUT_ERROR` | Request timeout - will auto-retry |
| `CONTENT_FILTER` | Prompt blocked by content policy |

## Development

### Setup

```bash
git clone https://github.com/GeorgH93/z_ai_image_gen_mcp.git
cd z_ai_image_gen_mcp
npm install
cp .env.example .env
# Edit .env with your API key
```

### Scripts

```bash
npm run build        # Build TypeScript
npm run dev          # Run in development mode
npm test             # Run all tests
npm run test:unit    # Run unit tests only
npm run test:integration  # Run integration tests
npm run test:e2e     # Run E2E tests
npm run test:coverage    # Run tests with coverage
npm run typecheck    # Type check without emit
```

## License

MIT

## Links

- [Z.AI Documentation](https://docs.z.ai/)
- [MCP Documentation](https://modelcontextprotocol.io/)
- [Get API Key](https://z.ai/manage-apikey/apikey-list)
- [GLM Coding Plan](https://z.ai/subscribe?ic=E7H8IV5TXG)