# zimage-mcp

MCP server exposing all [z-image.ai](https://z-image.ai) AI services — 45 tools for image generation, video generation, image editing, and utilities.

Works with GitHub Copilot CLI, Claude Desktop, and any MCP client.

## Quick Start

```bash
# Install dependencies
npm install

# Build
npm run build

# Authenticate (opens browser for Google login)
node dist/index.js auth

# Test
node dist/index.js status
```

## Authentication

z-image.ai uses Google OAuth. Run the auth flow once:

```bash
# Interactive: opens browser, guides you through cookie extraction
node dist/index.js auth

# Direct token (if you already have the session cookie):
node dist/index.js auth --token "YOUR_SESSION_TOKEN"

# Or set via environment variable:
export ZIMAGE_SESSION_TOKEN="your-token-here"
```

Session tokens are stored in `~/.config/zimage-mcp/auth.json`.

## MCP Client Configuration

### GitHub Copilot CLI

Add to your MCP config (`~/.config/github-copilot/mcp.json` or similar):

```json
{
  "mcpServers": {
    "zimage": {
      "command": "node",
      "args": ["/path/to/zimageai/dist/index.js"]
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "zimage": {
      "command": "node",
      "args": ["/path/to/zimageai/dist/index.js"],
      "env": {
        "ZIMAGE_SESSION_TOKEN": "optional-token-here"
      }
    }
  }
}
```

## Tools (45 total)

### Text-to-Image (10 tools)

| Tool | Model | Credits |
|------|-------|---------|
| `zimage_generate` | Z-Image (default) | 2 |
| `zimage_turbo_t2i` | Z-Image Turbo | 2 |
| `nano_banana_t2i` | Nano Banana | 2 |
| `nano_banana_pro_t2i` | Nano Banana Pro | 2 |
| `nano_banana_2_t2i` | Nano Banana 2 | 2 |
| `seedream_v45_t2i` | Seedream V4.5 | 2 |
| `seedream_50_lite_t2i` | Seedream 5.0 Lite | 2 |
| `flux_2_klein_t2i` | Flux 2 Klein | 2 |
| `gpt_image_1_t2i` | GPT Image 1 / DALL-E | 10 |
| `qwen_t2i` | Qwen | 2 |

### Image-to-Image (10 tools)

| Tool | Model | Credits |
|------|-------|---------|
| `image_to_image` | General I2I | 6 |
| `flux_2_klein_i2i` | Flux 2 Klein | 2 |
| `soul_i2i` | Soul (artistic) | 2 |
| `zimage_turbo_i2i` | Z-Image Turbo | 2 |
| `grok_imagine` | Grok Imagine (xAI) | 6 |
| `seedream_50_lite_i2i` | Seedream 5.0 Lite | 2 |
| `qwen_max_i2i` | Qwen Max | 4 |
| `nano_banana_i2i` | Nano Banana | 2 |
| `nano_banana_2_i2i` | Nano Banana 2 | 2 |
| `nano_banana_pro_edit` | Nano Banana Pro Edit | 2 |

### Image Utilities (4 tools)

| Tool | Description | Credits |
|------|-------------|---------|
| `image_eraser` | Remove objects from images | 10 |
| `background_remover` | Remove background (→ transparent PNG) | 2 |
| `image_upscaler` | AI upscale 2x/4x | 4 |
| `image_layered` | Decompose into semantic layers | 20/layer |

### Text-to-Video (5 tools)

| Tool | Model | Credits |
|------|-------|---------|
| `wan_26_t2v` | Wan 2.6 | 200-300 |
| `ltx2_fast_t2v` | LTX-2 Fast | 20 |
| `veo_31_t2v` | Google Veo 3.1 | 200 |
| `seedance_15_pro_t2v` | Seedance 1.5 Pro | 100 |
| `pixverse_56_t2v` | PixVerse v5.6 | 100 |

### Image-to-Video (5 tools)

| Tool | Model | Credits |
|------|-------|---------|
| `ltx2_fast_i2v` | LTX-2 Fast | 20 |
| `veo_31_i2v` | Google Veo 3.1 | 200 |
| `seedance_15_pro_i2v` | Seedance 1.5 Pro | 100 |
| `pixverse_56_i2v` | PixVerse v5.6 | 100 |
| `vidu_q3_i2v` | Vidu Q3 | 100 |

### Video Special (3 tools)

| Tool | Description | Credits |
|------|-------------|---------|
| `motion_control_kling` | Motion control with Kling 2.6 Pro | 200 |
| `video_face_swap` | Face swap in videos | 25/5s |
| `longcat_avatar` | Talking head avatar from audio+image | 80 |

### Account & Utility (8 tools)

| Tool | Description |
|------|-------------|
| `get_user_info` | Get user profile |
| `get_credits` | Check credit balance |
| `get_config` | Get app configuration |
| `prompt_enhance` | AI prompt enhancement |
| `estimate_credits` | Estimate generation cost |
| `upload_image` | Upload image to z-image.ai storage |
| `upload_video` | Upload video to z-image.ai storage |
| `upload_audio` | Upload audio to z-image.ai storage |

## Architecture

- **Runtime**: Node.js with ES modules
- **Transport**: stdio (standard MCP)
- **Auth**: Cookie-based session (Better Auth + Google OAuth)
- **Concurrency**: All tools are stateless — multiple generations can run in parallel
- **Polling**: Async task polling (submit → taskId → poll every 2.5s → output URL)

## Development

```bash
npm run build    # Compile TypeScript
npm run dev      # Build + run
npm start        # Run compiled server
```

## Notes

- All API endpoints were reverse-engineered from z-image.ai's JavaScript bundles
- No official API documentation exists — endpoints may change without notice
- Session cookies may expire; re-run `auth` if you get authentication errors
- File paths passed to tools are auto-uploaded before generation