Content
Grok Imagine Server
[](https://www.npmjs.com/package/grok-imagine-video-mcp-server)
[](https://opensource.org/licenses/MIT)
MCP (Model Context Protocol) server for Grok Imagine Video API. Supports video generation from text prompts, image-to-video, and video editing.
## Quick Start (npx)
The easiest way is to use `npx`:
```bash
# Set API key
export XAI_API_KEY="xai-your-api-key"
# Run the server
npx grok-imagine-video-mcp-server
```
## Features
- **Text-to-Video**: Generate new videos from text prompts
- **Image-to-Video**: Generate videos from images (optional prompt)
- **Reference-to-Video / R2V**: Generate videos using reference images as style/content references
- **Video Editing**: Edit existing videos with prompts
- **Video Extension**: Extend existing videos
- **Batch Processing**: Process multiple videos at once using CLI
- Supports various aspect ratios (16:9, 4:3, 1:1, 9:16, etc.)
- Resolutions: 480p, 720p, 1080p (1080p is limited to `grok-imagine-video-1.5` × Image-to-Video)
- Video length: 1-15 seconds (default 8 seconds; editing uses original video length, extension is 1-10 seconds)
- Asynchronous processing with polling for results, progress, and cost display
> **grok-imagine-video 1.5 support**: Includes Reference-to-Video, video extension, structured error/progress, and actual cost (`cost_in_usd_ticks`) display. 1080p is only available for Image-to-Video with `grok-imagine-video-1.5`.
## Supported Models
| Model | Features | Notes |
|--------|----------|------|
| `grok-imagine-video` | T2V / I2V / R2V / Editing / Extension | **Recommended and default**. All 1.5 generation features work with this model |
| `grok-imagine-video-1.5` | Centered around I2V (pinned version) | Does not support T2V/R2V/extension. For specific use cases only |
> **Model and feature compatibility (verified)**:
> Reference-to-Video, video extension, and Text-to-Video all work with the base model `grok-imagine-video` (official documentation examples use this model). The pinned version `grok-imagine-video-1.5` does not accept T2V/R2V/extension, so use the default `grok-imagine-video` model normally.
>
> **About 1080p**: According to the official documentation ([Video Generation](https://docs.x.ai/developers/model-capabilities/video/generation)), 1080p is only available for **Image-to-Video with `grok-imagine-video-1.5`**. Specifying `1080p` with other model-mode combinations returns `1080p video resolution is not available for this model.`. This is **unrelated to account permissions or Grok subscriptions (SuperGrok, etc.)**. xAI API billing is separate from consumer Grok subscriptions, and API functionality is not unlocked by subscription.
## Requirements
- Node.js 18.0.0 or higher
- xAI API key (obtain from [.ai](https://console.x.ai Installation
### Method 1: npx (recommended)
```bashpx grok-imagine-video-mcp-server### Method 2: Global Installation
```bash
-g grok-imagine-video-mgrok-imagine-video-mcp-server## Configuration
### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `XAI_API_KEY` | Yes | xAI API key |
| `DEBUG` | No | Enable debug logs with `true` |
| `OUTPUT_DIR` | No | Default output directory for videos |
| `VIDEO_POLL_INTERVAL` | No | Polling interval (milliseconds, default: 5000) |
| `VIDEO_MAX_POLL_ATTEMPTS` | No | Maximum polling attempts (default: 120) |
Desktop Configuration
****: `~/ Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\_desktop_config.json`
```json
{
"mcpServers": {
"grok-imagine-video": {
"command": "npx",
"args": ["-y", "grok-imagine-video-mcp-server"],
"env": {
"XAI_API_KEY": "xai-your-api-key-here"
}
}
}
}
```
## Tools
### generate_video
Generate videos from text prompts or images.
| Parameter | Type | Required | Description |
|-----------|-----|----------|-------------|
| `prompt` | string | Conditional | Description text for generated video. Required for T2V/R2V, optional for I2V (when image is specified) |
| `output_path` | string | No | Output file path (default: generated_video.mp4) |
| `model` | string | Model (default: grok-imagine-video) |
| `duration` | number | No | Video length (1-15 seconds, default: 8) |
| `aspect_ratio` | string | No | Aspect ratio (default: 16:9) |
| `resolution` | string | No | Resolution (480p/720p/1080p, default: 720p) |
| `image_url` | string | No | Input image URL for Image-to-Video |
| `image_path` | string | No | Local image file path (sent as base64 data URL; automatically uploaded via Files API if >10MB) |
| `image_file_id` | string | No | xAI Files API File ID (for Image-to-Video) |
| `reference_images` | array | No | Reference images for Reference-to-Video (each element can be `url`, `path`, or `file |
> ** Only one of `image_url`, `image_path`, or `image_file_id` can be specified. Also, cannot specify both image (I2V) and `reference_images` (R2V).
### edit_video
Edit existing videos.
| Parameter | Type | Required | Description |
|-----------|-----|----------|-------------|
| `prompt` | string | Yes | Description of edit |
| `video_url` | string | No* | URL of video to edit (publicly accessible, max 8.7 seconds) |
| `video_path` | string | No* | Local video file path (.mp4, automatically uploaded via Files API) |
| `video_file_id` | string | No* | xAI Files API File ID (*specify one of these) |
| `output_path` | string | No | Output file path (default: edited_video.mp4) |
| `model` | string | No | Model (default: grok-imagine-video) |
> **Note**: Edited video will have the same length as the original. `duration` parameter cannot be specified during editing.
### extend_video
Extend existing videos (grok-imagine-video 1.5).
| Parameter | Type | Required | Description |
|-----------|-----|----------|-------------|
| `prompt` | string | Yes of what happens in the continuation |
| `video_url` | string | No* | URL of extend ( or base URL, .mp4) |
| `video_path` | string | No* | Local video file path (.mp4, automatically uploaded via Files API) |
| `video_file_id` | string | No* | x API File ID (*specify one) |
| `output_path` | string | No file path: extended_video.mp4) |
model` | string | No |default: grok-imagine-video) |
| `duration` | number | No | Length of extension segment (1-10 seconds, default: 6) |
### upload_file
Upload local image/video files to xAI Files API and obtain_id`.
| Type | Required | Description |
|-----------|-------------|
| `file_path` | string | Yes | Path of file to upload (image:/png/gif/webp/bmp/tiff, video: mp4, max 48MB) |
## Batch Processing CLI
### Command Format
```
grok-imagine-video-batch <config.json> [options]
```
or via npx:
```
npx grok-imagine-video-batch <config.json> [options]
```
### Basic Usage Examples
```bash
# Batch execution with config file
npx grok-imagine-video-batch batch.json
# Cost estimation only (no execution)
npx grok-imagine-video-batch batch.json --estimate-only
# Specify output directory and format
npx grok-imagine-video-batch batch.json --output-dir ./videos --format json
# Customize polling settings
npx grok-imagine-video-batch batch.json --poll-interval 10000 --max-poll-attempts 60
# High parallel execution (with extended timeout)
npx grok-imagine-video-batch batch.json --max-concurrent 5 --timeout 1800000
# Display help
npx grok-imagine-video-batch --help
# Display version
npx grok-imagine-video-batch --version
```
###
| Option | Short | Argument | Description | Default |
|--------|--------|----------|-------------|-----------|
| `--output-dir` | - | `<path>` | Override output directory | From config file |
| `--format` | - | `text\|json` | Output format | `text` |
| `--timeout` | - | `< | Timeout (milliseconds, min 1000) |000` |
| `--max-concurrent` | - | `<n>` | Maximum concurrent jobs (1- | `2` `--poll-interval` | - | `<ms>`ing interval (milliseconds, min 1000) | `5000` |
| `--max-poll-attempts` | - | `<n>` | Maximum polling attempts | `120` |
| `--estimate-only` | - | - | Cost estimation only (no execution) | - |
| `--allow-any-path` | - | - | Allow arbitrary output paths (for CI/CD) | - |
| `--help` | `-h` | - | Display help message | - |
| `--version` | `-v` | - | Display version | - |
### Exit Codes
| Code | Meaning |
|--------|---------|
| `0` | Success (all jobs completed) |
| `1` | Error (failure or cancellation occurred) |
### Batch Config File
```json
{
"jobs": [
{
"promptA cat playing with a ball",
"output_path": "cat_video.mp4",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p"
},
{
"prompt": "An animated character walking",
"image_url": "https://example.com/character.jpg",
"output_path": "walking.mp4",
"duration": 10
},
{
"prompt": "Make the ball bigger",
"video_url": "https://example.com/video.mp4",
"output_path": "edited.mp4"
}
],
_dir": "./output",
"max_concurrent": 2,
"poll_interval": 5000,
"max_poll_attempts": 120,
"default_model": "grok-imagine-video",
"default_duration": 5,
"retry_policy": {
"max_retries": 2,
"retry_delay_ms": 1000
}
}
```
### Job Definition Schema
Each job specifies one of three types:
#### 1. Text-to-Video
```json
{
"prompt": "Description of video to generate",
"output_path": "output.mp4",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p",
"model": "grok-imagine-video"
}
```
| Field | Type | Required | Description |
|-----------|-----|----------|-------------|
| `prompt` | Yes | Video description text |
| `output_path` | string | No | Output file name |
| `duration` | number | No | Video length (1-15 seconds) |
| `aspect_ratio` | string | No | Aspect ratio |
| `resolution` | string | No | Resolution (720p/480p) |
| `model` | string | No | Model name |
#### 2. Image-to-Video
**URL specified:**
```json
{
"prompt": "Description to animate the image",
"image_url": "https://example.com/image.jpg",
"output_path": "animated.mp4",
"duration": 5
}
```
**Local file (base64 data URL):**
```json
{
"prompt": "Description to animate the image",
"image_path": "./images/character.jpg",
"output_path": "animated.mp4",
"duration": 5
}
```
| Field | Type | Required | Description |
|-----------|-----|----------|-------------|
| `prompt` | string | Yes | Animation description |
| `image_url` | string | No* | Input image URL (publicly accessible) |
| `image_path` | string | No* | Local image file path (sent as base64 data URL; automatically uploaded via Files API if >10MB) |
| `image_file_id` | string | No* | xAI Files API File ID |
| `output_path` | string | No | Output file name |
| `duration` | number | No | Video length (1-15 seconds) |
> *Specify `image_url`,_path`, or_file_id` ( multiple).
3. Reference-to-Video (R2V)
```json
{
"prompt": "A character walking in an anime style",
"reference [
{ "url": "https://example.com/style.jpg" },
{ "path": "./character.png" }
"output_path": "v.mp4",
"duration": 8
}
```
| Field | Type | Required | Description |
|-----------|-----|------|------|
prompt` | string | Yes | Description of the video |
| `reference_images` | array | Yes | Reference images (each element can be `url`, `path`, or `file_id`) |
| `output_path` | string | No | name |
| `duration` | number | No | Video1-15 seconds) |
> Image (I2V) and `reference_images` (R2V) cannot be specified simultaneously.
#### 4. Video Editjson
{
"prompt": "Description of the edit",
"video_url": "https://example.com/video.mp4",
"output_path": "edited.mp4"
}
```
| Field | Type | Required | Description |
|-----------|-----|------|------|
| `prompt` | string | Yes | Description of the edit |
| `video_url` | string | No* | URL of the video to edit (up to 8.7 seconds) |
video_path` | string | No* | Local video file path (.mp4, automatically uploaded via Files API) |
| `video_file_id` | string | No* | File ID of xAI Files API (* specify one of them) |
| `output_path` | string | No | Output file name |
#### 5.
```json
{
"operation": "extend",
"prompt": "The camera zooms out to show the cityscape",
"video_url": "https.com/video.mp4",
output_path": "extended.mp4",
"duration": }
```
| Field | Type | Required | Description |
|-----------|------|
| `operation string | Yes | Specify `"extend"` (omitting it will as an edit with a source video) |
| `prompt` | string | Yes | Description of next |
| `video_url` | string | No* | URL of the video to extend |
| `video_path` | string* | Local video file path (.mp4, automatically uploaded via Files API) |
| `video_file_id` | string | No* | File ID of xAI Files API (* specify one of them) |
| `output_path` | string | No | Output file name |
| `duration` | number | No | Length of the extension segment (1-10 seconds, default 6) |
> Jobs with `video_url`, `video_path`, or `video_file_id` are treated as edits by default. To extend, explicitly specify `"operation": "extend"`.
### Global Settings
| Field | Type | Description | Default |
|-----------|-----|------|-----------|
| `output_dir` | string directory | `./output` |
| `max_concurrent` | number | Maximum number of concurrent executions (1-10) | ` |
| `poll_interval number | Polling interval (ms) | `5000`max_poll_attempts number | Maximum number of polling attempts | `120` |
| `default_model` | string | | `grok-im` |
| `default_duration` | number | Default video `8` |
| `pect_ratio` | string | Default aspect ratio | `16` |
| `default_resolution` | string | Default resolution720p` |
### Retry Policyjson
{
"": {
"max_retries": 2,
_delay_ms": "retry_on_errors": ["rate_limit", "429", "500", "502", "503"]
}
}
```
| Type | Description ||-----------|-----|------|----------- `max_retries` | number | Maximum number of retries | `2` |
| `retry_delay_ms` | number | Retry delay (ms) | `1000` |
| `retry_on_errors` | string[] | Errors to retry on | See above |
Example settings can be found in the `examples/` directory:
- `batch-simple.json` - Basic video generation
- `batch-image-to-video.json` - Video generation from an image (URL specified)
- `batch-local-images.json` - Video generation from local images
- `batch-reference-to-video.json` - Video generation from reference images (R2V)
- `batch-with-edits.json` - Video editing chain
- `batch-extend.json` - Video extension
- `batch-social-media.json` - Social media format
## Supported Aspect Ratios
| Aspect Ratio | Example Use Case |
|-------------|------------------|
| `16:9` | Widescreen, YouTube (default) |
| `4:3` | Standard landscape |
| `1:1` | Square, Instagram |
| `9:16` | Portrait, TikTok, Reels, Stories |
| `3:4` | Portrait |
| `3:2` / `2:3` | Photo ratio |
## Supported Resolutions
| Resolution | Description |
|------------|------------|
| `1080p` | Full HD quality (** `grok-imagine-video-1.5` × Image-to-Video. Other combinations will result in "1080p video resolution is not available for this model."**) |
| `720p` | HD quality (default) |
| `480p` | Standard quality |
## Video Length Limitations
| Operation | Minimum | Maximum | Default |
|------|------|------|-----------|
| Generation (Text/Image/Reference-to-Video) | 1 second | 15 seconds | 8 seconds |
| Edit | - | 8.7 seconds | Same as original video |
| 1 second | seconds | 6 seconds |
## Asynchronous Processing
The Video asynchronously:
1. ****: Send a video generation
2. **Get `request_id`**: API `request_id`
3. **Polling**: Periodically check the result (default: every 5 seconds)
4. **Get Result**: After completion, retrieve the video URL and download
```
POST /v1/videos/generations → { request_id: "abc123" }
↓
GET /v1/videos/abc123 → { status: "pending" } → Wait
↓
GET /v1/videos/abc123 → { status: "completed", url: "..." } → Download
```
## Usage Examples
```
# Generate a video from text
"Create5-second video of a cat playing with a ball in 9"
# Generate a an image
"Create of this image's character walking"
# Edit a video
the background of this video to nighttime"
```
## API| Function | Endpoint |
|------|---------------|
| Video Generation (T2V/I2VV) | `POSTapi.x.ai/v1/videosations` |
| Video Edit | `POST https://api.x.ai/v1/videos/edits` |
| Video Extension | `POST https://api.x.ai/v1/videos/extensions` |
| Get Result | `GET https://api.x.ai/v1/videos/{request_id}` |
- **Documentation**: [docs.x.ai](https://docs.x.ai/)
## Development
```bash
git clone https://github.com/ex-takashima/grok-imagine-video-mcp-server.git
cd grok-imagine-video-mcp-server
npm install
npm run build
npm start
```
### Development Commands
```bash
# Build
npm run build
# Watch mode
npm run dev
# Run batch CLI
npm run batch -- examples/batch-simpleestimate-only
```
### Polling TimesVideo generation may take time:
```bash
# Increase polling attempts
npx grok-imagine-video-batch batch.json --max-poll-attempts 200
# Extend timeout
npx grok-imagine-video-batch batch.json --timeout 1200000
```
### Rate Limit Error
Reduce parallelism or adjust retry settings:
```json
{
"max_concurrent": 1,
"retry_policy": {
"max_retries": 3,
"retry_delay_ms": 5000,
"retry_on_errors": ["rate_limit", "429"]
}
}
```
## Related Projects
- [grok-imagine-image-mcp-server](https://github.com/ex-takashima/grok-imagine-image-mcp-server) - Image generation MCP Server
## License
MIT
## Author
Junji Takashima <takajyun00@gmail.com>
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available