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!

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.

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

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

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.

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

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

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

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

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

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:

npm install -g imaginepro-mcp-server

For local development:

cd imaginepro-mcp-server
npm install
npm run build

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:

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

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

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