PierrunoYT/replicate-ideogram-v3-mcp-server

Replicate Ideogram V3 Balanced MCP Server

A Model Context Protocol (MCP) server that provides access to the ideogram-ai/ideogram-v3-balanced image generation model via Replicate. This server allows you to generate high-quality images using advanced AI technology through the Replicate platform.

Features

• High-Quality Image Generation: Generate stunning images using the ideogram-ai/ideogram-v3-balanced model
• Multiple Generation Methods: Support for synchronous and asynchronous generation with prediction tracking
• Flexible Sizing Options: Support for various aspect ratios and custom resolutions
• Advanced Parameters: Control over magic prompt optimization, style types, and more
• Inpainting Support: Use images and masks for targeted image editing
• Style Reference Images: Apply custom style references for specialized image aesthetics
• Local Image Download: Automatically downloads generated images to local storage
• Prediction Management: Create, track, and cancel predictions
• Webhook Support: Optional webhook notifications for completed requests

Installation

Option 1: Universal npx Installation (Recommended)

No local installation required! Use npx to run the server directly:

npx -y https://github.com/PierrunoYT/replicate-ideogram-v3-mcp-server.git

Option 2: Local Installation

1. Clone this repository:

git clone https://github.com/PierrunoYT/replicate-ideogram-v3-mcp-server.git
cd replicate-ideogram-v3-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Environment Variables

Set your Replicate API token as an environment variable:

export REPLICATE_API_TOKEN="r8_NBY**********************************"

You can get your API token from Replicate.

MCP Client Configuration

Universal npx Configuration (Recommended)

Add this server to your MCP client configuration:

{
  "mcpServers": {
    "replicate-ideogram-v3": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/replicate-ideogram-v3-mcp-server.git"
      ],
      "env": {
        "REPLICATE_API_TOKEN": "r8_NBY**********************************"
      }
    }
  }
}

Local Installation Configuration

For local installations, use:

{
  "mcpServers": {
    "replicate-ideogram-v3": {
      "command": "node",
      "args": ["/path/to/replicate-ideogram-v3-mcp-server/build/index.js"],
      "env": {
        "REPLICATE_API_TOKEN": "r8_NBY**********************************"
      }
    }
  }
}

Available Tools

1. ideogram_v3_generate

Generate images using the standard synchronous method.

Parameters:

• prompt (required): Text prompt for image generation
• aspect_ratio (optional): Aspect ratio (default: "1:1")
  • Options: "1:3", "3:1", "1:2", "2:1", "9:16", "16:9", "10:16", "16:10", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "1:1"
• resolution (optional): Specific resolution (overrides aspect_ratio)
  • Many options from "512x1536" to "1536x640"
• magic_prompt_option (optional): Magic prompt optimization ("Auto", "On", "Off", default: "Auto")
• image (optional): Image file for inpainting (requires mask)
• mask (optional): Black and white mask for inpainting
• style_type (optional): Style aesthetic ("None", "Auto", "General", "Realistic", "Design", default: "None")
• style_reference_images (optional): Array of style reference image URLs
• seed (optional): Random seed for reproducible results

Example:

{
  "prompt": "The text \"V3 Balanced\" in the center middle. A color film-inspired portrait of a young man and a young woman looking at each other, a shallow depth of field that blurs the surrounding elements, drawing attention to their eyes.",
  "aspect_ratio": "3:2",
  "magic_prompt_option": "On",
  "style_type": "Realistic"
}

2. ideogram_v3_generate_async

Generate images using asynchronous method with prediction tracking.

Parameters: Same as ideogram_v3_generate plus:

• webhook (optional): URL for webhook notifications
• webhook_events_filter (optional): Events to send to webhook (default: ["completed"])

Returns: A prediction ID for tracking the job

3. ideogram_v3_get_prediction

Get the status and results of a prediction created with ideogram_v3_generate_async.

Parameters:

• prediction_id (required): The prediction ID from async generation

4. ideogram_v3_cancel_prediction

Cancel a running prediction to prevent unnecessary work and reduce costs.

Parameters:

• prediction_id (required): The prediction ID to cancel

Aspect Ratios and Resolutions

Supported Aspect Ratios

• 1:1 - Square
• 3:2, 2:3 - Classic photo ratios
• 4:3, 3:4 - Standard ratios
• 16:9, 9:16 - Widescreen ratios
• 4:5, 5:4 - Social media ratios
• 1:2, 2:1 - Tall/wide ratios
• 1:3, 3:1 - Ultra tall/wide ratios
• 10:16, 16:10 - Extended ratios

Custom Resolutions

You can specify exact resolutions from 512x1536 up to 1536x640 pixels. The resolution parameter overrides the aspect_ratio setting.

Magic Prompt

The Magic Prompt feature interprets and optimizes your prompts to maximize variety and quality:

• Auto - Automatically decides when to use magic prompt
• On - Always applies magic prompt optimization
• Off - Uses your prompt exactly as written

Magic Prompt also supports prompts in different languages.

Style Types

Control the aesthetic of generated images:

• None - No specific style applied
• Auto - Automatically selects appropriate style
• General - General purpose style
• Realistic - Photorealistic style
• Design - Design-focused style

Inpainting

Use the image and mask parameters for targeted image editing:

• image: The base image to edit
• mask: Black and white image where black pixels are inpainted and white pixels are preserved

Style Reference Images

Provide an array of image URLs in style_reference_images to guide the style of generated images.

Output

Generated images are automatically downloaded to a local images/ directory with descriptive filenames. The response includes:

• Local file paths
• Original URLs
• Image filenames
• Generation parameters used
• Prediction IDs for tracking

Error Handling

The server provides detailed error messages for:

• Missing API tokens
• Invalid parameters
• Network issues
• API rate limits
• Generation failures

Development

Running in Development Mode

npm run dev

Testing the Server

npm test

Getting the Installation Path

npm run get-path

API Reference

This server implements the ideogram-ai/ideogram-v3-balanced API via Replicate. For detailed API documentation, visit:

• Replicate Ideogram V3 Balanced
• Replicate API Documentation

License

MIT License - see file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions:

• Open an issue on GitHub
• Check the Replicate documentation

Changelog

v1.0.0

• Initial release with ideogram-ai/ideogram-v3-balanced integration
• Support for synchronous and asynchronous generation
• Prediction tracking and management
• Inpainting support with image and mask
• Style reference images support
• Magic prompt optimization
• Multiple aspect ratios and custom resolutions
• Local image download functionality
• Comprehensive error handling