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
• Text-to-Image Generation: Create images from text prompts with advanced AI
• Inpainting Support: Edit existing images using masks for targeted modifications
• Style Transfer: Apply custom styles using reference images and 60+ artistic presets
• Flexible Sizing Options: Support for 15 aspect ratios and 65+ custom resolutions
• Advanced Controls: Seed-based reproducible generation, magic prompt optimization
• Local Image Storage: Automatically downloads generated images to local storage
• Prediction Tracking: Monitor generation status and retrieve results
• Comprehensive Schema: Full support for all Ideogram V3 parameters

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

Generate images using the Ideogram V3 Balanced model with comprehensive parameter support.

Parameters:

• prompt (required): Text prompt for image generation
• aspect_ratio (optional): Aspect ratio (default: "1:1")
  • Options: "1:1", "1:2", "2:1", "1:3", "3:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "10:16", "16:10"
• resolution (optional): Specific resolution (overrides aspect_ratio, default: "None")
  • 65+ options from "512x1536" to "1536x640"
• magic_prompt_option (optional): Magic prompt optimization (default: "Auto")
  • Options: "Auto", "On", "Off"
• image (optional): Image file for inpainting (requires mask)
• mask (optional): Black and white mask for inpainting
• style_type (optional): Style aesthetic (default: "None")
  • Options: "None", "Auto", "General", "Realistic", "Design"
• style_reference_images (optional): Array of style reference image URLs
• seed (optional): Random seed for reproducible results (0-2147483647)
• style_preset (optional): Predefined artistic style (default: "None")
  • 60+ options including: "Art Deco", "Cubism", "Oil Painting", "Watercolor", "Pop Art", "Vintage Poster", etc.

Example:

{
  "prompt": "A majestic mountain landscape at sunset with vibrant colors",
  "aspect_ratio": "16:9",
  "magic_prompt_option": "On",
  "style_type": "Realistic",
  "style_preset": "Golden Hour",
  "seed": 12345
}

2. get_image_status

Check the status of an image generation request using a prediction ID.

Parameters:

• prediction_id (required): The prediction ID to check status for

Returns: Status information including completion state, errors, logs, and generated image URLs when complete.

Aspect Ratios and Resolutions

Supported Aspect Ratios

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

Custom Resolutions

Choose from 65+ specific resolutions ranging from 512x1536 to 1536x640 pixels. The resolution parameter overrides the aspect_ratio setting when specified.

Popular Resolutions:

• 1024x1024 - Square HD
• 1536x640 - Ultra-wide
• 768x1344 - Portrait
• 1344x768 - Landscape

Magic Prompt

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

• Auto (default) - 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 and can enhance simple prompts with rich details.

Style Controls

Style Types

Control the overall aesthetic approach:

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

Style Presets

Choose from 60+ predefined artistic styles:

Art Movements:

• Art Deco, Art Brut, Bauhaus, Cubism, Pop Art

Photography Styles:

• Golden Hour, Long Exposure, Dramatic Cinema, Editorial

Artistic Techniques:

• Oil Painting, Watercolor, Woodblock Print, Halftone Print

Design Styles:

• Flat Art, Minimal Illustration, Blueprint, Vintage Poster

And many more including: 80s Illustration, Anime, Graffiti, Surreal Collage, Travel Poster, etc.

Inpainting

Use the image and mask parameters for targeted image editing:

• image: The base image to edit (URL or file path)
• mask: Black and white image where black pixels are inpainted and white pixels are preserved

Inpainting Example:

{
  "prompt": "A beautiful garden with flowers",
  "image": "https://example.com/base-image.jpg",
  "mask": "https://example.com/mask.jpg"
}

Style Reference Images

Provide an array of image URLs in style_reference_images to guide the style of generated images. The model will analyze these references and apply similar aesthetic qualities to your generation.

Style Reference Example:

{
  "prompt": "A modern cityscape",
  "style_reference_images": [
    "https://example.com/style1.jpg",
    "https://example.com/style2.jpg"
  ]
}

Reproducible Generation

Use the seed parameter (0-2147483647) to generate reproducible results. The same prompt with the same seed will produce identical images.

Reproducible Example:

{
  "prompt": "A red rose in a garden",
  "seed": 42,
  "aspect_ratio": "1:1"
}

Output

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

• Image URLs: Direct links to generated images
• Local Paths: Local file locations for downloaded images
• Generation Details: All parameters used in generation
• Metadata: Timestamps, filenames, and technical details

Example Output:

Successfully generated image with Ideogram V3 Balanced model.

**Prompt:** A majestic mountain landscape at sunset
**Aspect Ratio:** 16:9
**Style Preset:** Golden Hour
**Seed:** 12345

**Generated Images:**
1. https://replicate.delivery/pbxt/abc123.png

**Local Copies:**
1. /path/to/generated_images/ideogram_2024-01-15T10-30-00-000Z_1.png

Error Handling

The server provides detailed error messages for:

• Missing or invalid API tokens
• Invalid parameter values
• Network connectivity issues
• API rate limits and quotas
• Generation failures and timeouts
• File download errors

Development

Running in Development Mode

npm run dev

Testing the Server

npm test

Building the Project

npm run build

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
• Model Context Protocol

Examples

Basic Text-to-Image

{
  "prompt": "A cute cat wearing a wizard hat"
}

High-Resolution Landscape

{
  "prompt": "Epic mountain vista with dramatic clouds",
  "resolution": "1536x640",
  "style_preset": "Dramatic Cinema"
}

Artistic Portrait

{
  "prompt": "Portrait of a wise old man",
  "aspect_ratio": "3:4",
  "style_type": "Realistic",
  "style_preset": "Oil Painting"
}

Reproducible Design

{
  "prompt": "Modern logo design for a tech company",
  "aspect_ratio": "1:1",
  "style_type": "Design",
  "seed": 2024,
  "magic_prompt_option": "Off"
}

License

MIT License - see LICENSE 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
• Review the MCP specification

Changelog

v1.0.0

• Initial release with ideogram-ai/ideogram-v3-balanced integration
• Comprehensive parameter support with full schema implementation
• Text-to-image generation with 60+ style presets
• Inpainting support with image and mask parameters
• Style reference images for custom aesthetics
• Magic prompt optimization with multilingual support
• 15 aspect ratios and 65+ custom resolutions
• Seed-based reproducible generation
• Local image download with organized storage
• Robust error handling and status tracking