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.

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!

Table of Contents

• 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):

Claude Code

Quick Install (Recommended):

Make your API key permanent:

Manual Configuration:

Edit your MCP settings:

Using Shell Environment Variable:

Configure without the env block:

Then export in your shell:

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:

Install globally with npm:

Then configure:

For development or customization:

Then configure:

Codex

Add to ~/.codex/config.toml:

Get Your API Key

1. Sign up at imaginepro.ai

2. Navigate to your account settings

3. Generate an API key

4. Copy and use it in the configuration above

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):

Windsurf (Codeium)

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

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

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

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:

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:

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:

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:

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:

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:

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:

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:

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:

The assistant will automatically:

1. Call generate-image with your prompt

2. Return the image URL and message ID

3. Display the result

Example 2: Multi-Modal Image Editing

Combine existing images with text descriptions:

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

Example 3: Video Generation Workflow

Create smooth video transitions:

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

Example 4: Image Enhancement Pipeline

Complete workflow for refining images:

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

Example 5: Async Status Tracking

Monitor long-running generations:

Uses fetch-status to monitor progress of asynchronous operations.

Environment Variables

Configuration Files

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

File locations (checked in order):

1. ~/.imaginepro/config.json (global)

2. ./.imaginepro.json (project-specific)

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

Priority: Environment variables > Config file > Defaults

Custom Timeout Example

For video generation or large batches:

Prerequisites

• Node.js >= 18.0.0

• npm or yarn

• TypeScript knowledge

• An ImaginePro API key for testing

Setup

Commands

Testing with Claude Desktop

Point your config to your local build:

Troubleshooting

Common Issues

"IMAGINEPRO_API_KEY environment variable is required"

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

Solutions:

1. Ensure your API key is set in the MCP configuration:

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

2. Or export it in your shell before starting:

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

3. 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:

For local development:

Server Not Responding

1. Check if the server is actually running (look for startup message in logs)

2. Verify the command path in your MCP configuration is correct

3. Ensure Node.js >= 18.0.0 is installed: node --version

4. 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:

"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:

1. Find your node path:

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

2. 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:

1. Check the logs: Most MCP clients provide detailed logs

2. Review examples: See the Usage Examples section

3. Open an issue: GitHub Issues

4. Contact support: ImaginePro Support

Contributing

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

Quick Start

1. Fork and clone the repository

2. Create a feature branch: git checkout -b feature/amazing-feature

3. Make your changes and test them

4. Commit: git commit -m 'Add amazing feature'

5. Push: git push origin feature/amazing-feature

6. 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