ImaginePro MCP Server

A fast and powerful MCP (Model Context Protocol) server that brings ImaginePro AI image and video generation capabilities to your AI assistants like Claude, enabling seamless creative content generation through natural language.

What's New in v1.1.0 🎉

Major Improvements:

Automatic Completion Waiting: All generation tools now automatically wait for tasks to complete before returning results
Real-time Progress Updates: See generation progress in real-time during image and video creation
Fixed URL Mapping: Corrected image/video URL field mapping to ensure reliable access to generated content
Enhanced Response Data: All tools now return status and progress information for better tracking
Improved Error Handling: More descriptive error messages with standardized formatting

Breaking Changes: None - all changes are backward compatible!

Why ImaginePro MCP?
Features
Quick Start
Installation
Tools Reference
Usage Examples
Troubleshooting
Contributing

Why ImaginePro MCP?

🚀 Fast & Lightweight: Optimized for quick image and video generation
🎨 Comprehensive: Support for text-to-image, video generation, upscaling, variants, and inpainting
🔧 Easy Integration: Works with Claude Desktop, Claude Code, and any MCP-compatible tool
🎯 Production Ready: Built with TypeScript, full error handling, and robust API integration
📦 Simple Setup: Install with npx or npm in seconds

Features

Text-to-Image Generation: Create stunning AI images from text descriptions
Multi-modal Generation: Combine text and images for advanced generation (Gemini)
Video Generation: Create smooth video animations from start and end frames
Image Upscaling: Enhance image resolution and quality
Image Variants: Generate alternative versions of existing images
Image Rerolling: Regenerate images with the same prompt
Inpainting: Edit specific regions of images using masks
Status Tracking: Check the progress of generation tasks in real-time

Quick Start

Prerequisites

Node.js >= 18.0.0
An ImaginePro API key (sign up for free)
Claude Desktop, Claude Code, or any MCP-compatible tool

Installation

The ImaginePro MCP server can be installed in multiple ways depending on your tool and preference.

Option 1: Quick Install with npx (Recommended)

The easiest way to get started - no installation needed!

Claude Desktop

Add to your ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Claude Code

Quick Install (Recommended):

# Set your API key first
export IMAGINEPRO_API_KEY="sk-your-api-key-here"

# Add the server with the API key
claude mcp add-json imaginepro '{"command":"npx","args":["-y","imaginepro-mcp-server"],"env":{"IMAGINEPRO_API_KEY":"'"$IMAGINEPRO_API_KEY"'"}}' -s local

Make your API key permanent:

echo 'export IMAGINEPRO_API_KEY="sk-your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

Alternative Installation Methods

Manual Configuration:

Edit your MCP settings:

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Using Shell Environment Variable:

Configure without the env block:

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"]
    }
  }
}

Then export in your shell:

export IMAGINEPRO_API_KEY="sk-your-api-key-here"

Note: The MCP configuration env block takes precedence over shell environment variables.

Other MCP Tools

For tools like Cursor, Goose, or LM Studio, use similar configuration:

{
  "imaginepro": {
    "command": "npx",
    "args": ["-y", "imaginepro-mcp-server"],
    "env": {
      "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
    }
  }
}

Option 2: Global Installation

Install globally with npm:

npm install -g imaginepro-mcp-server

Then configure:

{
  "mcpServers": {
    "imaginepro": {
      "command": "imaginepro-mcp-server",
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Option 3: Local Development

For development or customization:

git clone https://github.com/imaginpro/imaginepro-mcp-server.git
cd imaginepro-mcp-server
npm install
npm run build

Then configure:

{
  "mcpServers": {
    "imaginepro": {
      "command": "node",
      "args": ["/absolute/path/to/imaginepro-mcp-server/dist/index.js"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.imaginepro]
command = "npx"
args = ["-y", "imaginepro-mcp-server"]

[mcp_servers.imaginepro.env]
IMAGINEPRO_API_KEY = "sk-your-api-key-here"

Get Your API Key

Sign up at imaginepro.ai
Navigate to your account settings
Generate an API key
Copy and use it in the configuration above

Configuration for Other MCP Clients

The ImaginePro MCP server works with many popular AI development tools. Below are specific configuration instructions for each client.

Cursor

Add to your Cursor settings (.cursor/config.json or via Settings UI):

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Windsurf (Codeium)

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Gemini CLI, VS Code, Goose, LM Studio, Warp Terminal, Amp

For most other MCP-compatible tools, use the standard configuration:

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Note: Some tools may use slightly different config keys (e.g., mcp.servers for VS Code, amp.mcpServers for Amp). Refer to your tool's MCP documentation.

Tools Reference

Available Tools (8 total)

The ImaginePro MCP server provides 8 powerful tools for AI image and video generation. All tools return structured responses with URLs to generated content.

Core Generation Tools

`generate-image`

Generate AI images from text descriptions using advanced text-to-image models.

Parameters:

prompt (string, required): Detailed description of the image to generate
ref (string, optional): Reference ID for tracking
webhookOverride (string, optional): Webhook URL for async notifications

Returns:

messageId: Unique identifier for the generated image
imageUrl: Direct URL to the generated image
status: Generation status (DONE, FAIL, etc.)
progress: Completion percentage (0-100)

Note: This tool now waits for the image to complete before returning (typically 30-60 seconds).

Example Usage:

Generate a photorealistic image of a serene mountain lake at sunrise, with mist rising from the water and pine trees reflected in the still surface

`gemini-imagine`

Generate images using multi-modal inputs, combining text prompts with existing images.

Parameters:

contents (array, required): Array of content items with type ('text' or 'image'), text, and url
model (string, optional): Model to use (default: gemini-2.5-flash-image-preview)
ref (string, optional): Reference ID for tracking
webhookOverride (string, optional): Webhook URL

Returns:

messageId: Unique identifier
imageUrl: Direct URL to the generated image
status: Generation status
progress: Completion percentage

Note: Automatically waits for completion before returning.

Example Usage:

Use this image [cat.jpg] and make the cat wearing a royal crown and sitting on a throne

`generate-video`

Create smooth video animations transitioning between two frames.

Parameters:

prompt (string, required): Description of the video transition/animation
startFrameUrl (string, required): URL of the starting frame image
endFrameUrl (string, required): URL of the ending frame image
ref (string, optional): Reference ID
webhookOverride (string, optional): Webhook URL

Returns:

messageId: Unique identifier
videoUrl: Direct URL to the generated video
status: Generation status
progress: Completion percentage

Note: Video generation takes longer (typically 1-3 minutes). The tool waits for completion.

Example Usage:

Create a smooth morphing video between sunset.jpg and night.jpg with a natural day-to-night transition

Image Enhancement Tools

`upscale-image`

Enhance image resolution and quality using AI upscaling.

Parameters:

messageId (string, required): Message ID of the image to upscale
ref (string, optional): Reference ID
webhookOverride (string, optional): Webhook URL

Returns:

messageId: New message identifier
imageUrl: URL to the upscaled image
status: Generation status
progress: Completion percentage

Note: Waits for upscaling to complete before returning.

Example Usage:

Upscale the image with message ID abc123 to higher resolution

`create-variant`

Generate alternative versions of an existing image with different styles or variations.

Parameters:

messageId (string, required): Message ID of the base image
ref (string, optional): Reference ID
webhookOverride (string, optional): Webhook URL

Returns:

messageId: New message identifier
imageUrl: URL to the variant image
status: Generation status
progress: Completion percentage

Note: Waits for variant generation to complete before returning.

Example Usage:

Create a variant of the image abc123

`reroll-image`

Regenerate an image using the same original prompt.

Parameters:

messageId (string, required): Message ID of the image to reroll
ref (string, optional): Reference ID
webhookOverride (string, optional): Webhook URL

Returns:

messageId: New message identifier
imageUrl: URL to the new image
status: Generation status
progress: Completion percentage

Note: Waits for regeneration to complete before returning.

Example Usage:

Reroll the image abc123 to get a different result

Image Editing Tools

`inpaint-image`

Edit specific regions of an image by providing a mask indicating areas to modify.

Parameters:

messageId (string, required): Message ID of the base image
maskUrl (string, required): URL of the mask image (white areas will be edited)
prompt (string, required): Description of what to generate in masked areas
ref (string, optional): Reference ID
webhookOverride (string, optional): Webhook URL

Returns:

messageId: New message identifier
imageUrl: URL to the inpainted image
status: Generation status
progress: Completion percentage

Note: Waits for inpainting to complete before returning.

Example Usage:

Inpaint the image abc123 using mask at mask.png and add a rainbow in the sky

Utility Tools

`fetch-status`

Check the real-time status and progress of any generation task.

Parameters:

messageId (string, required): Message ID to check status for

Returns:

status: Current status (pending, processing, completed, failed)
progress: Progress percentage (0-100)
imageUrl: URL of generated image (when ready)
videoUrl: URL of generated video (when ready)

Example Usage:

Check the status of generation task abc123

Usage Examples

Here are practical examples demonstrating different use cases with the ImaginePro MCP server.

Example 1: Simple Image Generation

Just describe what you want in natural language:

Generate an image of a cozy coffee shop interior with warm lighting, wooden furniture,
and customers reading books. Make it photorealistic.

The assistant will automatically:

Call generate-image with your prompt
Return the image URL and message ID
Display the result

Combine existing images with text descriptions:

I have this image of a cat at cat.jpg. Can you make it wearing a wizard hat
and holding a magic wand, maintaining the same artistic style?

Uses gemini-imagine to process both the image and your modification request.

Example 3: Video Generation Workflow

Create smooth video transitions:

I have two images: sunset-beach.jpg and night-beach.jpg.
Create a 5-second video showing the smooth transition from day to night.

Calls generate-video to create an animated transition between frames.

Example 4: Image Enhancement Pipeline

Complete workflow for refining images:

1. Generate an image of a fantasy castle
2. Create 3 variants to see different options
3. Upscale the best variant to higher resolution
4. Use inpainting to add dragons flying in the sky

This demonstrates chaining multiple tools together for a complete creative workflow.

Example 5: Async Status Tracking

Monitor long-running generations:

Check the status of my video generation task abc123

Uses fetch-status to monitor progress of asynchronous operations.

Advanced Configuration

Environment Variables

Variable	Required	Default	Description
`IMAGINEPRO_API_KEY`	Yes	-	Your ImaginePro API key from imaginepro.ai
`IMAGINEPRO_BASE_URL`	No	`https://api.imaginepro.ai`	Custom API endpoint (for enterprise users)
`IMAGINEPRO_TIMEOUT`	No	`300000` (5 min)	Request timeout in milliseconds

Configuration Files

You can use a JSON configuration file instead of environment variables:

File locations (checked in order):

~/.imaginepro/config.json (global)
./.imaginepro.json (project-specific)

Example (~/.imaginepro/config.json):

{
  "apiKey": "sk-your-api-key-here",
  "baseUrl": "https://api.imaginepro.ai",
  "timeout": 300000
}

Priority: Environment variables > Config file > Defaults

Custom Timeout Example

For video generation or large batches:

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key",
        "IMAGINEPRO_TIMEOUT": "600000"
      }
    }
  }
}

Development Guide

Prerequisites

Node.js >= 18.0.0
npm or yarn
TypeScript knowledge
An ImaginePro API key for testing

Setup

git clone https://github.com/imaginpro/imaginepro-mcp-server.git
cd imaginepro-mcp-server
npm install
npm run build

Commands

Command	Description
`npm run build`	Compile TypeScript to JavaScript
`npm run dev`	Watch mode - auto-rebuild on changes
`npm start`	Run the compiled server
`npm run clean`	Remove build artifacts

Testing with Claude Desktop

Point your config to your local build:

{
  "mcpServers": {
    "imaginepro-dev": {
      "command": "node",
      "args": ["/absolute/path/to/imaginepro-mcp-server/dist/index.js"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-test-key"
      }
    }
  }
}

Troubleshooting

Common Issues & Solutions

Common Issues

"IMAGINEPRO_API_KEY environment variable is required"

Cause: The server couldn't find your API key.

Solutions:

Ensure your API key is set in the MCP configuration:

"env": {
  "IMAGINEPRO_API_KEY": "sk-your-actual-key"
}

Or export it in your shell before starting:

export IMAGINEPRO_API_KEY="sk-your-api-key"

Restart your MCP client (Claude Desktop, etc.) after changing configuration

"Failed to generate image" or API Errors

Possible causes and solutions:

Invalid API key: Verify your key at imaginepro.ai
Insufficient credits: Check your account balance
Network issues: Verify internet connection and firewall settings
Rate limiting: Wait a few moments and try again
Invalid parameters: Check that image URLs are accessible and prompts are valid

"Module not found" or Import Errors

For npm package installation:

npm install -g imaginepro-mcp-server

For local development:

cd imaginepro-mcp-server
npm install
npm run build

Server Not Responding

Check if the server is actually running (look for startup message in logs)
Verify the command path in your MCP configuration is correct
Ensure Node.js >= 18.0.0 is installed: node --version
Check MCP client logs for detailed error messages

"Command not found: imaginepro-mcp"

This happens when using global installation but the binary isn't in PATH.

Solution: Use npx instead:

{
  "command": "npx",
  "args": ["-y", "imaginepro-mcp-server"]
}

"spawn node ENOENT" or "Failed to connect" (Claude Code with nvm)

Cause: If you're using nvm (Node Version Manager), Claude Code cannot find the node executable because it doesn't inherit your shell's PATH.

Error in logs: spawn node /path/to/dist/index.js ENOENT

Solution: Use the full path to node in your configuration:

Find your node path:

which node
# Example output: /Users/username/.nvm/versions/node/v22.19.0/bin/node

Update your MCP configuration to use the full path:

{
  "mcpServers": {
    "imaginepro": {
      "command": "/Users/username/.nvm/versions/node/v22.19.0/bin/node",
      "args": ["/absolute/path/to/imaginepro-mcp-server/dist/index.js"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Alternative: If using the published npm package with npx, this issue doesn't occur since npx handles the node executable automatically.

Getting Help

If you're still experiencing issues:

Check the logs: Most MCP clients provide detailed logs
Review examples: See the Usage Examples section
Open an issue: GitHub Issues
Contact support: ImaginePro Support

Contributing

How to Contribute

We welcome contributions! Whether it's bug reports, feature requests, documentation improvements, or code contributions.

Quick Start

Fork and clone the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and test them
Commit: git commit -m 'Add amazing feature'
Push: git push origin feature/amazing-feature
Open a Pull Request

Guidelines

Follow TypeScript best practices
Use clear, descriptive commit messages
Update documentation as needed
Test with Claude Desktop before submitting

Reporting Issues

Include:

Your environment (OS, Node version, MCP client)
Steps to reproduce
Expected vs actual behavior
Error messages and logs

Support & Links

ImaginePro API: imaginepro.ai | Support
GitHub Issues: Report bugs or request features
Documentation: Claude Code | MCP Protocol

License

MIT License - see LICENSE file for details.

Built with Model Context Protocol | Powered by ImaginePro AI

ImaginePro MCP Server

What's New in v1.1.0 🎉

Major Improvements:

Automatic Completion Waiting: All generation tools now automatically wait for tasks to complete before returning results
Real-time Progress Updates: See generation progress in real-time during image and video creation
Fixed URL Mapping: Corrected image/video URL field mapping to ensure reliable access to generated content
Enhanced Response Data: All tools now return status and progress information for better tracking
Improved Error Handling: More descriptive error messages with standardized formatting

Breaking Changes: None - all changes are backward compatible!

Why ImaginePro MCP?
Features
Quick Start
Installation
Tools Reference
Usage Examples
Troubleshooting
Contributing

Why ImaginePro MCP?

🚀 Fast & Lightweight: Optimized for quick image and video generation
🎨 Comprehensive: Support for text-to-image, video generation, upscaling, variants, and inpainting
🔧 Easy Integration: Works with Claude Desktop, Claude Code, and any MCP-compatible tool
🎯 Production Ready: Built with TypeScript, full error handling, and robust API integration
📦 Simple Setup: Install with npx or npm in seconds

Features

Text-to-Image Generation: Create stunning AI images from text descriptions
Multi-modal Generation: Combine text and images for advanced generation (Gemini)
Video Generation: Create smooth video animations from start and end frames
Image Upscaling: Enhance image resolution and quality
Image Variants: Generate alternative versions of existing images
Image Rerolling: Regenerate images with the same prompt
Inpainting: Edit specific regions of images using masks
Status Tracking: Check the progress of generation tasks in real-time

Quick Start

Prerequisites

Node.js >= 18.0.0
An ImaginePro API key (sign up for free)
Claude Desktop, Claude Code, or any MCP-compatible tool

Installation

The ImaginePro MCP server can be installed in multiple ways depending on your tool and preference.

Option 1: Quick Install with npx (Recommended)

The easiest way to get started - no installation needed!

Claude Desktop

Add to your ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Claude Code

Quick Install (Recommended):

# Set your API key first
export IMAGINEPRO_API_KEY="sk-your-api-key-here"

# Add the server with the API key
claude mcp add-json imaginepro '{"command":"npx","args":["-y","imaginepro-mcp-server"],"env":{"IMAGINEPRO_API_KEY":"'"$IMAGINEPRO_API_KEY"'"}}' -s local

Make your API key permanent:

echo 'export IMAGINEPRO_API_KEY="sk-your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

Alternative Installation Methods

Manual Configuration:

Edit your MCP settings:

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Using Shell Environment Variable:

Configure without the env block:

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"]
    }
  }
}

Then export in your shell:

export IMAGINEPRO_API_KEY="sk-your-api-key-here"

Note: The MCP configuration env block takes precedence over shell environment variables.

Other MCP Tools

For tools like Cursor, Goose, or LM Studio, use similar configuration:

{
  "imaginepro": {
    "command": "npx",
    "args": ["-y", "imaginepro-mcp-server"],
    "env": {
      "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
    }
  }
}

Option 2: Global Installation

Install globally with npm:

npm install -g imaginepro-mcp-server

Then configure:

{
  "mcpServers": {
    "imaginepro": {
      "command": "imaginepro-mcp-server",
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Option 3: Local Development

For development or customization:

git clone https://github.com/imaginpro/imaginepro-mcp-server.git
cd imaginepro-mcp-server
npm install
npm run build

Then configure:

{
  "mcpServers": {
    "imaginepro": {
      "command": "node",
      "args": ["/absolute/path/to/imaginepro-mcp-server/dist/index.js"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.imaginepro]
command = "npx"
args = ["-y", "imaginepro-mcp-server"]

[mcp_servers.imaginepro.env]
IMAGINEPRO_API_KEY = "sk-your-api-key-here"

Get Your API Key

Sign up at imaginepro.ai
Navigate to your account settings
Generate an API key
Copy and use it in the configuration above

Configuration for Other MCP Clients

The ImaginePro MCP server works with many popular AI development tools. Below are specific configuration instructions for each client.

Cursor

Add to your Cursor settings (.cursor/config.json or via Settings UI):

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Windsurf (Codeium)

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Gemini CLI, VS Code, Goose, LM Studio, Warp Terminal, Amp

For most other MCP-compatible tools, use the standard configuration:

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Note: Some tools may use slightly different config keys (e.g., mcp.servers for VS Code, amp.mcpServers for Amp). Refer to your tool's MCP documentation.

Tools Reference

Available Tools (8 total)

The ImaginePro MCP server provides 8 powerful tools for AI image and video generation. All tools return structured responses with URLs to generated content.

Core Generation Tools

`generate-image`

Generate AI images from text descriptions using advanced text-to-image models.

Parameters:

prompt (string, required): Detailed description of the image to generate
ref (string, optional): Reference ID for tracking
webhookOverride (string, optional): Webhook URL for async notifications

Returns:

messageId: Unique identifier for the generated image
imageUrl: Direct URL to the generated image
status: Generation status (DONE, FAIL, etc.)
progress: Completion percentage (0-100)

Note: This tool now waits for the image to complete before returning (typically 30-60 seconds).

Example Usage:

Generate a photorealistic image of a serene mountain lake at sunrise, with mist rising from the water and pine trees reflected in the still surface

`gemini-imagine`

Generate images using multi-modal inputs, combining text prompts with existing images.

Parameters:

contents (array, required): Array of content items with type ('text' or 'image'), text, and url
model (string, optional): Model to use (default: gemini-2.5-flash-image-preview)
ref (string, optional): Reference ID for tracking
webhookOverride (string, optional): Webhook URL

Returns:

messageId: Unique identifier
imageUrl: Direct URL to the generated image
status: Generation status
progress: Completion percentage

Note: Automatically waits for completion before returning.

Example Usage:

Use this image [cat.jpg] and make the cat wearing a royal crown and sitting on a throne

`generate-video`

Create smooth video animations transitioning between two frames.

Parameters:

prompt (string, required): Description of the video transition/animation
startFrameUrl (string, required): URL of the starting frame image
endFrameUrl (string, required): URL of the ending frame image
ref (string, optional): Reference ID
webhookOverride (string, optional): Webhook URL

Returns:

messageId: Unique identifier
videoUrl: Direct URL to the generated video
status: Generation status
progress: Completion percentage

Note: Video generation takes longer (typically 1-3 minutes). The tool waits for completion.

Example Usage:

Create a smooth morphing video between sunset.jpg and night.jpg with a natural day-to-night transition

Image Enhancement Tools

`upscale-image`

Enhance image resolution and quality using AI upscaling.

Parameters:

messageId (string, required): Message ID of the image to upscale
ref (string, optional): Reference ID
webhookOverride (string, optional): Webhook URL

Returns:

messageId: New message identifier
imageUrl: URL to the upscaled image
status: Generation status
progress: Completion percentage

Note: Waits for upscaling to complete before returning.

Example Usage:

Upscale the image with message ID abc123 to higher resolution

`create-variant`

Generate alternative versions of an existing image with different styles or variations.

Parameters:

messageId (string, required): Message ID of the base image
ref (string, optional): Reference ID
webhookOverride (string, optional): Webhook URL

Returns:

messageId: New message identifier
imageUrl: URL to the variant image
status: Generation status
progress: Completion percentage

Note: Waits for variant generation to complete before returning.

Example Usage:

Create a variant of the image abc123

`reroll-image`

Regenerate an image using the same original prompt.

Parameters:

messageId (string, required): Message ID of the image to reroll
ref (string, optional): Reference ID
webhookOverride (string, optional): Webhook URL

Returns:

messageId: New message identifier
imageUrl: URL to the new image
status: Generation status
progress: Completion percentage

Note: Waits for regeneration to complete before returning.

Example Usage:

Reroll the image abc123 to get a different result

Image Editing Tools

`inpaint-image`

Edit specific regions of an image by providing a mask indicating areas to modify.

Parameters:

messageId (string, required): Message ID of the base image
maskUrl (string, required): URL of the mask image (white areas will be edited)
prompt (string, required): Description of what to generate in masked areas
ref (string, optional): Reference ID
webhookOverride (string, optional): Webhook URL

Returns:

messageId: New message identifier
imageUrl: URL to the inpainted image
status: Generation status
progress: Completion percentage

Note: Waits for inpainting to complete before returning.

Example Usage:

Inpaint the image abc123 using mask at mask.png and add a rainbow in the sky

Utility Tools

`fetch-status`

Check the real-time status and progress of any generation task.

Parameters:

messageId (string, required): Message ID to check status for

Returns:

status: Current status (pending, processing, completed, failed)
progress: Progress percentage (0-100)
imageUrl: URL of generated image (when ready)
videoUrl: URL of generated video (when ready)

Example Usage:

Check the status of generation task abc123

Usage Examples

Here are practical examples demonstrating different use cases with the ImaginePro MCP server.

Example 1: Simple Image Generation

Just describe what you want in natural language:

Generate an image of a cozy coffee shop interior with warm lighting, wooden furniture,
and customers reading books. Make it photorealistic.

The assistant will automatically:

Call generate-image with your prompt
Return the image URL and message ID
Display the result

Combine existing images with text descriptions:

I have this image of a cat at cat.jpg. Can you make it wearing a wizard hat
and holding a magic wand, maintaining the same artistic style?

Uses gemini-imagine to process both the image and your modification request.

Example 3: Video Generation Workflow

Create smooth video transitions:

I have two images: sunset-beach.jpg and night-beach.jpg.
Create a 5-second video showing the smooth transition from day to night.

Calls generate-video to create an animated transition between frames.

Example 4: Image Enhancement Pipeline

Complete workflow for refining images:

1. Generate an image of a fantasy castle
2. Create 3 variants to see different options
3. Upscale the best variant to higher resolution
4. Use inpainting to add dragons flying in the sky

This demonstrates chaining multiple tools together for a complete creative workflow.

Example 5: Async Status Tracking

Monitor long-running generations:

Check the status of my video generation task abc123

Uses fetch-status to monitor progress of asynchronous operations.

Advanced Configuration

Environment Variables

Variable	Required	Default	Description
`IMAGINEPRO_API_KEY`	Yes	-	Your ImaginePro API key from imaginepro.ai
`IMAGINEPRO_BASE_URL`	No	`https://api.imaginepro.ai`	Custom API endpoint (for enterprise users)
`IMAGINEPRO_TIMEOUT`	No	`300000` (5 min)	Request timeout in milliseconds

Configuration Files

You can use a JSON configuration file instead of environment variables:

File locations (checked in order):

~/.imaginepro/config.json (global)
./.imaginepro.json (project-specific)

Example (~/.imaginepro/config.json):

{
  "apiKey": "sk-your-api-key-here",
  "baseUrl": "https://api.imaginepro.ai",
  "timeout": 300000
}

Priority: Environment variables > Config file > Defaults

Custom Timeout Example

For video generation or large batches:

{
  "mcpServers": {
    "imaginepro": {
      "command": "npx",
      "args": ["-y", "imaginepro-mcp-server"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key",
        "IMAGINEPRO_TIMEOUT": "600000"
      }
    }
  }
}

Development Guide

Prerequisites

Node.js >= 18.0.0
npm or yarn
TypeScript knowledge
An ImaginePro API key for testing

Setup

git clone https://github.com/imaginpro/imaginepro-mcp-server.git
cd imaginepro-mcp-server
npm install
npm run build

Commands

Command	Description
`npm run build`	Compile TypeScript to JavaScript
`npm run dev`	Watch mode - auto-rebuild on changes
`npm start`	Run the compiled server
`npm run clean`	Remove build artifacts

Testing with Claude Desktop

Point your config to your local build:

{
  "mcpServers": {
    "imaginepro-dev": {
      "command": "node",
      "args": ["/absolute/path/to/imaginepro-mcp-server/dist/index.js"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-test-key"
      }
    }
  }
}

Troubleshooting

Common Issues & Solutions

Common Issues

"IMAGINEPRO_API_KEY environment variable is required"

Cause: The server couldn't find your API key.

Solutions:

Ensure your API key is set in the MCP configuration:

"env": {
  "IMAGINEPRO_API_KEY": "sk-your-actual-key"
}

Or export it in your shell before starting:

export IMAGINEPRO_API_KEY="sk-your-api-key"

Restart your MCP client (Claude Desktop, etc.) after changing configuration

"Failed to generate image" or API Errors

Possible causes and solutions:

Invalid API key: Verify your key at imaginepro.ai
Insufficient credits: Check your account balance
Network issues: Verify internet connection and firewall settings
Rate limiting: Wait a few moments and try again
Invalid parameters: Check that image URLs are accessible and prompts are valid

"Module not found" or Import Errors

For npm package installation:

npm install -g imaginepro-mcp-server

For local development:

cd imaginepro-mcp-server
npm install
npm run build

Server Not Responding

Check if the server is actually running (look for startup message in logs)
Verify the command path in your MCP configuration is correct
Ensure Node.js >= 18.0.0 is installed: node --version
Check MCP client logs for detailed error messages

"Command not found: imaginepro-mcp"

This happens when using global installation but the binary isn't in PATH.

Solution: Use npx instead:

{
  "command": "npx",
  "args": ["-y", "imaginepro-mcp-server"]
}

"spawn node ENOENT" or "Failed to connect" (Claude Code with nvm)

Cause: If you're using nvm (Node Version Manager), Claude Code cannot find the node executable because it doesn't inherit your shell's PATH.

Error in logs: spawn node /path/to/dist/index.js ENOENT

Solution: Use the full path to node in your configuration:

Find your node path:

which node
# Example output: /Users/username/.nvm/versions/node/v22.19.0/bin/node

Update your MCP configuration to use the full path:

{
  "mcpServers": {
    "imaginepro": {
      "command": "/Users/username/.nvm/versions/node/v22.19.0/bin/node",
      "args": ["/absolute/path/to/imaginepro-mcp-server/dist/index.js"],
      "env": {
        "IMAGINEPRO_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Alternative: If using the published npm package with npx, this issue doesn't occur since npx handles the node executable automatically.

Getting Help

If you're still experiencing issues:

Check the logs: Most MCP clients provide detailed logs
Review examples: See the Usage Examples section
Open an issue: GitHub Issues
Contact support: ImaginePro Support

Contributing

How to Contribute

We welcome contributions! Whether it's bug reports, feature requests, documentation improvements, or code contributions.

Quick Start

Fork and clone the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and test them
Commit: git commit -m 'Add amazing feature'
Push: git push origin feature/amazing-feature
Open a Pull Request

Guidelines

Follow TypeScript best practices
Use clear, descriptive commit messages
Update documentation as needed
Test with Claude Desktop before submitting

Reporting Issues

Include:

Your environment (OS, Node version, MCP client)
Steps to reproduce
Expected vs actual behavior
Error messages and logs

Support & Links

ImaginePro API: imaginepro.ai | Support
GitHub Issues: Report bugs or request features
Documentation: Claude Code | MCP Protocol

License

MIT License - see LICENSE file for details.

ImaginePro MCP Server

ImaginePro MCP Server

Table of Contents

Why ImaginePro MCP?

Features

Quick Start

Prerequisites

Installation

Option 1: Quick Install with npx (Recommended)

Claude Desktop

Claude Code

Other MCP Tools

Codex

Get Your API Key

Cursor

Windsurf (Codeium)

Gemini CLI, VS Code, Goose, LM Studio, Warp Terminal, Amp

Tools Reference

Core Generation Tools

generate-image

gemini-imagine

generate-video

Image Enhancement Tools

upscale-image

create-variant

reroll-image

Image Editing Tools

inpaint-image

Utility Tools

fetch-status

Usage Examples

Example 1: Simple Image Generation

Example 2: Multi-Modal Image Editing

Example 3: Video Generation Workflow

Example 4: Image Enhancement Pipeline

Example 5: Async Status Tracking

Environment Variables

Configuration Files

Custom Timeout Example

Prerequisites

Setup

Commands

Testing with Claude Desktop

Troubleshooting

Common Issues

"IMAGINEPRO_API_KEY environment variable is required"

"Failed to generate image" or API Errors

"Module not found" or Import Errors

Server Not Responding

"Command not found: imaginepro-mcp"

"spawn node ENOENT" or "Failed to connect" (Claude Code with nvm)

Getting Help

Contributing

Quick Start

Guidelines

Reporting Issues

Support & Links

License

ImaginePro MCP Server

Table of Contents

Why ImaginePro MCP?

Features

Quick Start

Prerequisites

Installation

Option 1: Quick Install with npx (Recommended)

Claude Desktop

Claude Code

Other MCP Tools

Codex

Get Your API Key

Cursor

Windsurf (Codeium)

Gemini CLI, VS Code, Goose, LM Studio, Warp Terminal, Amp

Tools Reference

Core Generation Tools

generate-image

gemini-imagine

generate-video

Image Enhancement Tools

`generate-image`

`gemini-imagine`

`generate-video`

`upscale-image`

`create-variant`

`reroll-image`

`inpaint-image`

`fetch-status`

`generate-image`

`gemini-imagine`

`generate-video`

`upscale-image`

`create-variant`

`reroll-image`

`inpaint-image`

`fetch-status`