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
- Clone this repository:
git clone https://github.com/PierrunoYT/replicate-ideogram-v3-mcp-server.git
cd replicate-ideogram-v3-mcp-server
- Install dependencies:
npm install
- 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 generationaspect_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 inpaintingstyle_type(optional): Style aesthetic (default: "None")- Options: "None", "Auto", "General", "Realistic", "Design"
style_reference_images(optional): Array of style reference image URLsseed(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 ratios1:3,3:1- Ultra tall/wide ratios2:3,3:2- Classic photo ratios3:4,4:3- Standard ratios4:5,5:4- Social media ratios9:16,16:9- Widescreen ratios10: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 HD1536x640- Ultra-wide768x1344- Portrait1344x768- 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 promptOn- Always applies magic prompt optimizationOff- 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 appliedAuto- Automatically selects appropriate styleGeneral- General purpose styleRealistic- Photorealistic styleDesign- 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:
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
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- 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