MCP server for xAI Grok Imagine Image API - Generate and edit images using grok-imagine-image model
npm install grok-imagine-image-mcp-server
MCP (Model Context Protocol) server for xAI's Grok Imagine Image API. Supports image generation from text prompts and editing existing images.
``bashSet your API key
export XAI_API_KEY="xai-your-api-key"
Features
- Image Generation: Generate new images from text prompts
- Image Editing: Edit existing images with prompts (grok-imagine-image only)
- Batch Processing: Process multiple images via CLI
- Various aspect ratios (1:1, 4:3, 16:9, and more)
- Resolution: 1k (standard)
- Generate multiple images at once (up to 10)
- Optional thumbnail preview in MCP responses
Supported Models
| Model | Price | Image Editing | Notes |
|-------|-------|---------------|-------|
|
| $0.02/image | ✅ (+$0.002/input) | Recommended, Default |Requirements
- Node.js 18.0.0 or higher
- xAI API key (get from console.x.ai)
Installation
$3
`bash
npx grok-imagine-image-mcp-server
`$3
bash
npm install -g grok-imagine-image-mcp-server
grok-imagine-image-mcp-server
`Configuration
$3
| Variable | Required | Description |
|----------|----------|-------------|
|
| Yes | Your xAI API key |
| DEBUG | No | Set to true for debug logging |
| OUTPUT_DIR | No | Default output directory for images |
| XAI_IMAGE_THUMBNAIL | No | Set to true to include thumbnails |$3
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows: json
{
"mcpServers": {
"grok-imagine-image": {
"command": "npx",
"args": ["-y", "grok-imagine-image-mcp-server"],
"env": {
"XAI_API_KEY": "xai-your-api-key-here"
}
}
}
}
`Tools
$3
Generate images from text prompts.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|
| string | Yes | Text description of the image to generate |
| output_path | string | No | Output file path (default: generated_image.jpg) |
| model | string | No | Model to use (default: grok-imagine-image) |
| n | number | No | Number of images (1-10, default: 1) |
| aspect_ratio | string | No | Aspect ratio (default: 1:1) |
| resolution | string | No | Resolution (default: 1k) |
| return_base64 | boolean | No | Return base64 data (default: false) |
| include_thumbnail | boolean | No | Include thumbnail (default: false) |$3
Edit existing images (grok-imagine-image only).
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|
prompt | string | Yes | Description of desired edits |
| image_path | string | No* | Path to source image file |
| image_base64 | string | No* | Base64 encoded source image |
| image_url | string | No* | URL of source image |
| output_path | string | No | Output file path (default: edited_image.jpg) |
| n | number | No | Number of images (1-10, default: 1) |
| resolution | string | No | Resolution (default: 1k). Aspect ratio is auto-detected from input image. |*One of
image_path, image_base64, or image_url is required> Note: The edit_image tool uses the source image as a reference and regenerates the entire image. It maintains the overall composition and style but is not pixel-level inpainting. Best suited for style transformations, subject replacements, and scene modifications.
Batch Processing CLI
Process multiple images at once using the batch CLI:
`bash
Run batch with config file
npx grok-imagine-image-batch batch.jsonEstimate cost only
npx grok-imagine-image-batch batch.json --estimate-onlyCustom output directory
npx grok-imagine-image-batch batch.json --output-dir ./images --format json
`$3
| Option | Description | Default |
|--------|-------------|---------|
|
| Override output directory | From config |
| --format | Output format | text |
| --timeout | Timeout in milliseconds | 600000 |
| --max-concurrent | Max concurrent jobs (1-10) | 2 |
| --estimate-only | Estimate cost without executing | - |
| --allow-any-path | Allow any output path (CI/CD) | - |$3
`json
{
"jobs": [
{
"prompt": "A beautiful sunset over mountains",
"output_path": "sunset.jpg",
"aspect_ratio": "16:9"
},
{
"prompt": "Change to nighttime scene",
"image_path": "input.jpg",
"output_path": "edited.jpg"
}
],
"output_dir": "./output",
"max_concurrent": 3,
"default_model": "grok-imagine-image",
"retry_policy": {
"max_retries": 2,
"retry_delay_ms": 1000
}
}
`See
directory for more configuration examples.Supported Aspect Ratios
| Aspect Ratio | Use Case |
|--------------|----------|
|
1:1 | Square, social media profiles (default) |
| 3:4 / 4:3 | Standard portrait/landscape |
| 9:16 / 16:9 | Smartphone / widescreen |Supported Resolutions
| Resolution | Description |
|------------|-------------|
|
1k | Standard resolution (1024x1024, default) |
Usage Examples
`
Image generation
Generate an image of a sunset over mountains with aspect ratio 16:9Image editing
Change the background of this image to space
API Reference
| Function | Endpoint |
|----------|----------|
| Image Generation |
|
| Image Editing | https://api.x.ai/v1/images/edits |- Documentation: docs.x.ai/docs/guides/image-generations
Development
`bash
git clone https://github.com/ex-takashima/grok-imagine-image-mcp-server.git
cd grok-imagine-image-mcp-server
npm install
npm run build
npm start
``MIT
Junji Takashima