# Jimeng Visual Generation MCP Server

An MCP server for Volcengine's (火山引擎) Jimeng Visual Generation API. Provides image and video generation capabilities through the Model Context Protocol.

## Features

- **Text-to-Image (T2I)**: Generate images from text prompts
- **Image-to-Image (I2I)**: Transform images based on prompts and references
- **Multi-Image Fusion**: Combine multiple reference images
- **Text-to-Video (T2V)**: Generate videos from text prompts
- **Image-to-Video (I2V)**: Create videos from first frame or first+last frame images
- **Automatic Local File Support**: Pass local file paths - they are automatically converted to Base64

## Installation

### Option 1: Install via pip

```bash
pip install jimeng_visual_generation
```

### Option 2: Run directly with uvx (Recommended)

No installation needed. `uvx` will automatically download and run the package:

```bash
uvx jimeng_visual_generation
```

## Configuration for VS Code / Cursor / Claude Desktop

Add the following to your MCP configuration file:

- **VS Code**: `~/.vscode/mcp.json` or workspace settings
- **Cursor**: Settings -> MCP Servers
- **Claude Desktop**: `%APPDATA%\Claude\claude_desktop_config.json`

### Example Configuration (with env variables)

```json
{
  "mcpServers": {
    "jimeng_visual_generation": {
      "command": "uvx",
      "args": ["jimeng_visual_generation"],
      "env": {
        "VOLC_API_KEY": "your_volcengine_api_key_here",
        "VOLC_IMAGE_MODEL": "doubao-seedream-4.5",
        "VOLC_VIDEO_MODEL": "doubao-seedance-1.5-pro-251215"
      }
    }
  }
}
```

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `VOLC_API_KEY` | ✅ Yes | Your Volcengine API Key |
| `VOLC_IMAGE_MODEL` | Optional | Image model ID (default: doubao-seedream-4.5) |
| `VOLC_VIDEO_MODEL` | Optional | Video model ID (default: doubao-seedance-1.5-pro) |

## Available Tools

### `generate_image`

Generate images using text prompts and optional reference images.

**Parameters:**

- `prompt` (required): Text description of the desired image
- `image_urls` (optional): List of reference images (URLs, Base64, or local file paths)
- `model` (optional): Model ID to use
- `size` (optional): Image dimensions (e.g., "2048x2048", "2K", "4K")

### `generate_video`

Create video generation tasks. Automatically detects mode based on input:

- No images → Text-to-Video
- 1 image → First Frame I2V
- 2 images → First & Last Frame I2V

**Parameters:**

- `prompt` (optional): Text description for the video
- `image_urls` (optional): Input images (URLs, Base64, or local file paths)
- `model` (optional): Model ID to use
- `ratio` (optional): Aspect ratio (e.g., "16:9", "9:16")
- `duration` (optional): Video length in seconds

### `get_video_task_result`

Query the status and result of a video generation task.

**Parameters:**

- `task_id` (required): Task ID returned by `generate_video`

## License

MIT
