Chol369/ideogram-mcp-server

Ideogram MCP Server

Complete Model Context Protocol (MCP) server implementation for Ideogram v3.0 API with all endpoints - Generate, Edit, Remix, Reframe, and Replace Background.

🎨 Overview

Ideogram MCP Server provides a complete implementation of Ideogram's v3.0 API through the Model Context Protocol, enabling AI assistants like Claude to generate, edit, and transform images with premium quality suitable for commercial use.

Why This Server?

• Complete API Coverage: All 5 Ideogram v3.0 endpoints implemented
• Premium Quality: Optimized for marketable, high-quality images
• Style Control: Advanced style references and preset system
• Enterprise Ready: Robust error handling and validation
• MCP Native: Seamless integration with Claude and other MCP clients

✨ Features

Complete Ideogram v3.0 API Implementation

1. Generate - Create images from text prompts

   • Style references (up to 3 images)
   • 15 aspect ratios
   • Rendering speed control (TURBO/DEFAULT/QUALITY)
   • Magic prompt enhancement
   • Batch generation (1-8 images)

2. Edit - Modify images with mask-based editing

   • Precise region control
   • Style-guided edits
   • Maintain image coherence

3. Remix - Transform existing images

   • Adjustable strength (0.0-1.0)
   • Style transfer capabilities
   • Multiple variations

4. Reframe - Change image aspect ratios

   • Smart content preservation
   • Multiple resolution options

5. Replace Background - Intelligent background replacement

   • Automatic subject detection
   • Style-consistent backgrounds

Premium Presets System

Pre-configured settings for marketable images:

• product-hero - E-commerce product photography
• marketing-banner - Professional marketing materials
• social-post - Engaging social media content
• editorial-photo - Magazine-quality images

🚀 Installation

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn
• Ideogram API key from ideogram.ai/manage-api

Quick Setup

1. Clone and install:

git clone https://github.com/Chol369/ideogram-mcp-server.git
cd ideogram-mcp-server
npm install
npm run build

2. Set up environment:

cp .env.example .env
# Edit .env and add your IDEOGRAM_API_KEY

Claude Desktop Integration

Add to your Claude Desktop configuration:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ideogram": {
      "command": "node",
      "args": [
        "C:\\Users\\chol3\\Desktop\\Gumroad\\ideogram-mcp-server\\dist\\index.js"
      ],
      "env": {
        "IDEOGRAM_API_KEY": "your_api_key_here"
      }
    }
  }
}

📖 Usage Examples

Generate Premium Product Image

Use the generate_image tool with:
- prompt: "Minimalist product photography of premium headphones on marble surface"
- preset: "product-hero"
- rendering_speed: "QUALITY"

Edit with Mask

Use the edit_image tool with:
- image_file: "path/to/image.jpg"
- mask: "path/to/mask.png"
- prompt: "Replace the text with 'SALE 50% OFF' in modern typography"

Remix for Variations

Use the remix_image tool with:
- image_file: "path/to/original.jpg"
- prompt: "Transform to cyberpunk aesthetic"
- strength: 0.7
- num_images: 4

Smart Background Replacement

Use the replace_background tool with:
- image_file: "path/to/product.jpg"
- prompt: "Luxury studio setup with gradient lighting"

🛠️ Available Tools

Core Generation Tools

Utility Tools

🎯 Premium Presets

Optimized settings for commercial use:

{
  "product-hero": {
    "rendering_speed": "QUALITY",
    "style_type": "REALISTIC",
    "magic_prompt": "ON",
    "aspect_ratio": "1x1"
  }
}

🔧 Configuration

Environment Variables

IDEOGRAM_API_KEY=your_api_key_here
OUTPUT_DIR=./generated
BASE_FILENAME=ideogram-image

Supported Formats

• Input: JPEG, PNG, WebP
• Output: PNG (default), JPEG
• Max file size: 10MB

📊 API Limits

• Default rate limit: 10 concurrent requests
• Image expiration: Download immediately (URLs expire)
• Max images per request: 8
• Max style references: 3

🏗️ Architecture

ideogram-mcp-server/
├── src/
│   ├── types/          # TypeScript definitions
│   ├── tools/          # MCP tool implementations
│   ├── utils/          # Validation and helpers
│   ├── ideogram-client.ts  # API client
│   ├── server.ts       # MCP server
│   └── index.ts        # Entry point
├── dist/               # Compiled JavaScript
└── generated/          # Output directory

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Submit a pull request

📄 License

MIT License - see file

🔗 Resources

• Ideogram API Documentation
• Model Context Protocol
• Claude Desktop

🙏 Acknowledgments

Built with inspiration from the Ideogram community and MCP ecosystem.

Created by Chol369 | Powered by Ideogram v3.0