imaginepro

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!

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

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

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

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