# 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:
```bash
npx -y https://github.com/PierrunoYT/replicate-ideogram-v3-mcp-server.git
```
### Option 2: Local Installation
1. Clone this repository:
```bash
git clone https://github.com/PierrunoYT/replicate-ideogram-v3-mcp-server.git
cd replicate-ideogram-v3-mcp-server
```
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
## Configuration
### Environment Variables
Set your Replicate API token as an environment variable:
```bash
export REPLICATE_API_TOKEN="r8_NBY**********************************"
```
You can get your API token from [Replicate](https://replicate.com/).
### MCP Client Configuration
#### Universal npx Configuration (Recommended)
Add this server to your MCP client configuration:
```json
{
"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:
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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
```bash
npm run dev
```
### Testing the Server
```bash
npm test
```
### Building the Project
```bash
npm run build
```
### Getting the Installation Path
```bash
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](https://replicate.com/ideogram-ai/ideogram-v3-balanced)
- [Replicate API Documentation](https://replicate.com/docs)
- [Model Context Protocol](https://modelcontextprotocol.io/)
## Examples
### Basic Text-to-Image
```json
{
"prompt": "A cute cat wearing a wizard hat"
}
```
### High-Resolution Landscape
```json
{
"prompt": "Epic mountain vista with dramatic clouds",
"resolution": "1536x640",
"style_preset": "Dramatic Cinema"
}
```
### Artistic Portrait
```json
{
"prompt": "Portrait of a wise old man",
"aspect_ratio": "3:4",
"style_type": "Realistic",
"style_preset": "Oil Painting"
}
```
### Reproducible Design
```json
{
"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](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](https://github.com/PierrunoYT/replicate-ideogram-v3-mcp-server/issues)
- Check the [Replicate documentation](https://replicate.com/docs)
- Review the [MCP specification](https://modelcontextprotocol.io/)
## 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
