# ImaginePro MCP Server
[](https://github.com/imaginpro/imaginepro-mcp-server/actions/workflows/build.yml)
[](https://www.npmjs.com/package/imaginepro-mcp-server)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
A fast and powerful MCP (Model Context Protocol) server that brings [ImaginePro](https://imaginepro.ai) AI image and video generation capabilities to your AI assistants like Claude, enabling seamless creative content generation through natural language.
<details>
<summary><b>What's New in v1.1.0</b> 🎉</summary>
**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!
</details>
## Table of Contents
- [Why ImaginePro MCP?](#why-imaginepro-mcp)
- [Features](#features)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Tools Reference](#tools-reference)
- [Usage Examples](#usage-examples)
- [Troubleshooting](#troubleshooting)
- [Contributing](#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](https://imaginepro.ai) (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):
```json
{
"mcpServers": {
"imaginepro": {
"command": "npx",
"args": ["-y", "imaginepro-mcp-server"],
"env": {
"IMAGINEPRO_API_KEY": "sk-your-api-key-here"
}
}
}
}
```
#### Claude Code
**Quick Install** (Recommended):
```bash
# 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:
```bash
echo 'export IMAGINEPRO_API_KEY="sk-your-api-key-here"' >> ~/.zshrc
source ~/.zshrc
```
<details>
<summary><b>Alternative Installation Methods</b></summary>
**Manual Configuration:**
Edit your MCP settings:
```json
{
"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:
```json
{
"mcpServers": {
"imaginepro": {
"command": "npx",
"args": ["-y", "imaginepro-mcp-server"]
}
}
}
```
Then export in your shell:
```bash
export IMAGINEPRO_API_KEY="sk-your-api-key-here"
```
**Note**: The MCP configuration `env` block takes precedence over shell environment variables.
</details>
#### Other MCP Tools
For tools like Cursor, Goose, or LM Studio, use similar configuration:
```json
{
"imaginepro": {
"command": "npx",
"args": ["-y", "imaginepro-mcp-server"],
"env": {
"IMAGINEPRO_API_KEY": "sk-your-api-key-here"
}
}
}
```
<details>
<summary><b>Option 2: Global Installation</b></summary>
Install globally with npm:
```bash
npm install -g imaginepro-mcp-server
```
Then configure:
```json
{
"mcpServers": {
"imaginepro": {
"command": "imaginepro-mcp-server",
"env": {
"IMAGINEPRO_API_KEY": "sk-your-api-key-here"
}
}
}
}
```
</details>
<details>
<summary><b>Option 3: Local Development</b></summary>
For development or customization:
```bash
git clone https://github.com/imaginpro/imaginepro-mcp-server.git
cd imaginepro-mcp-server
npm install
npm run build
```
Then configure:
```json
{
"mcpServers": {
"imaginepro": {
"command": "node",
"args": ["/absolute/path/to/imaginepro-mcp-server/dist/index.js"],
"env": {
"IMAGINEPRO_API_KEY": "sk-your-api-key-here"
}
}
}
}
```
</details>
#### Codex
Add to `~/.codex/config.toml`:
```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](https://imaginepro.ai)
2. Navigate to your account settings
3. Generate an API key
4. Copy and use it in the configuration above
<details>
<summary><b>Configuration for Other MCP Clients</b></summary>
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):
```json
{
"mcpServers": {
"imaginepro": {
"command": "npx",
"args": ["-y", "imaginepro-mcp-server"],
"env": {
"IMAGINEPRO_API_KEY": "sk-your-api-key-here"
}
}
}
}
```
### Windsurf (Codeium)
```json
{
"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:
```json
{
"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.
</details>
## Tools Reference
<details>
<summary><b>Available Tools (8 total)</b></summary>
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
```
</details>
## 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:
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:
```
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.
<details>
<summary><b>Advanced Configuration</b></summary>
### 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):
1. `~/.imaginepro/config.json` (global)
2. `./.imaginepro.json` (project-specific)
**Example** (`~/.imaginepro/config.json`):
```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:
```json
{
"mcpServers": {
"imaginepro": {
"command": "npx",
"args": ["-y", "imaginepro-mcp-server"],
"env": {
"IMAGINEPRO_API_KEY": "sk-your-api-key",
"IMAGINEPRO_TIMEOUT": "600000"
}
}
}
}
```
</details>
<details>
<summary><b>Development Guide</b></summary>
### Prerequisites
- Node.js >= 18.0.0
- npm or yarn
- TypeScript knowledge
- An ImaginePro API key for testing
### Setup
```bash
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:
```json
{
"mcpServers": {
"imaginepro-dev": {
"command": "node",
"args": ["/absolute/path/to/imaginepro-mcp-server/dist/index.js"],
"env": {
"IMAGINEPRO_API_KEY": "sk-your-test-key"
}
}
}
}
```
</details>
## Troubleshooting
<details>
<summary><b>Common Issues & Solutions</b></summary>
### 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:
```json
"env": {
"IMAGINEPRO_API_KEY": "sk-your-actual-key"
}
```
2. Or export it in your shell before starting:
```bash
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](https://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**:
```bash
npm install -g imaginepro-mcp-server
```
**For local development**:
```bash
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:
```json
{
"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:
```bash
which node
# Example output: /Users/username/.nvm/versions/node/v22.19.0/bin/node
```
2. Update your MCP configuration to use the full path:
```json
{
"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](#usage-examples) section
3. **Open an issue**: [GitHub Issues](https://github.com/imaginpro/imaginepro-mcp-server/issues)
4. **Contact support**: [ImaginePro Support](https://imaginepro.ai/support)
</details>
## Contributing
<details>
<summary><b>How to Contribute</b></summary>
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
</details>
## Support & Links
- **ImaginePro API**: [imaginepro.ai](https://imaginepro.ai) | [Support](https://imaginepro.ai/support)
- **GitHub Issues**: [Report bugs or request features](https://github.com/imaginpro/imaginepro-mcp-server/issues)
- **Documentation**: [Claude Code](https://docs.claude.com/en/docs/claude-code) | [MCP Protocol](https://modelcontextprotocol.io)
## License
MIT License - see [LICENSE](LICENSE) file for details.
---
Built with [Model Context Protocol](https://modelcontextprotocol.io) | Powered by [ImaginePro AI](https://imaginepro.ai)
