ideogram-mcp-server

Ideogram MCP Server

     

Warning: This is an unofficial, community-driven project and is not affiliated with, endorsed by, or sponsored by Ideogram AI. For official Ideogram resources, please visit ideogram.ai. Note: This project was entirely implemented by an AI agent (Claude) using the auto-claude autonomous development system. The codebase, tests, and documentation were all generated through AI-assisted development. Human oversight was provided for requirements and review.

A production-grade Model Context Protocol (MCP) server that provides seamless integration between LLM applications (Claude Desktop, Cursor, VS Code) and the Ideogram AI image generation API. Powered by Ideogram V3, it offers 10 tools for complete image generation, editing, and analysis workflows.

!demo

What's New in v3.0.0

• 5 New Tools -- Describe, Upscale, Remix, Reframe, and Replace Background (10 tools total)
• Character Reference Support -- Maintain visual consistency of characters across generations (generate, edit, remix)
• Ideogram V3 API -- Edit tool migrated from legacy API to V3 with rendering speed control
• Reframe replaces Outpainting -- Intelligent outpainting is now a dedicated tool with resolution targeting

Features

• Image Generation - Generate high-quality AI images from text prompts using Ideogram V3
• Image Editing - Mask-based inpainting to edit specific parts of images (V3 API)
• Image Description - Analyze images and generate detailed text descriptions
• Image Upscaling - Enhance image resolution with guided upscaling controls
• Image Remixing - Transform images with new prompts while preserving original characteristics
• Image Reframing - Extend images to new resolutions via intelligent outpainting
• Background Replacement - Automatically replace backgrounds while preserving foreground subjects
• Character References - Maintain character consistency across multiple generations
• Async Support - Queue generation requests for background processing
• Cost Tracking - Estimated credit and USD costs included in all responses
• Local Storage - Automatically save generated images locally (URLs expire)
• Enterprise Error Handling - User-friendly messages with retry guidance
• Type Safety - Full TypeScript strict mode with Zod validation

Quick Start

Prerequisites

• Node.js 18+
• An Ideogram API key

Installation

 

# Clone the repository
git clone https://github.com/takeshijuan/ideogram-mcp-server.git
cd ideogram-mcp-server

# Install dependencies
npm install

# Build
npm run build

Configuration

Create a .env file (or set environment variables):

# Required
IDEOGRAM_API_KEY=your_ideogram_api_key_here

# Optional
LOG_LEVEL=info                    # debug, info, warn, error
LOCAL_SAVE_DIR=./ideogram_images  # Where to save images
ENABLE_LOCAL_SAVE=true            # Auto-download generated images

Claude Desktop Setup

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "ideogram": {
      "command": "node",
      "args": ["/path/to/ideogram-mcp-server/dist/index.js"],
      "env": {
        "IDEOGRAM_API_KEY": "your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop to load the server.

Available Tools (10)

ideogram_generate

Generate images from text prompts.

// Basic usage
{
  prompt: "A beautiful sunset over mountains"
}

// With all options
{
  prompt: "A cute cat wearing a wizard hat",
  aspect_ratio: "16x9",    // 15 ratios: 1x1, 16x9, 9x16, 4x3, 3x4, etc.
  num_images: 4,           // 1-8 images
  rendering_speed: "QUALITY", // FLASH, TURBO, DEFAULT, QUALITY
  magic_prompt: "ON",      // AUTO, ON, OFF - enhance prompts
  style_type: "REALISTIC", // AUTO, GENERAL, REALISTIC, DESIGN, FICTION
  character_reference_images: ["https://example.com/char.jpg"],
  save_locally: true       // Save to local disk
}

Response includes:

• Image URLs and local paths (if saved)
• Seeds for reproducibility
• Cost estimates (credits and USD)

ideogram_edit

Edit specific parts of existing images using mask-based inpainting (V3 API).

// Edit parts of an image using a mask
{
  prompt: "Add a red balloon in the sky",
  image: "https://example.com/photo.jpg",  // URL, file path, or base64 data URL
  mask: maskImageData,  // Black pixels=edit, White pixels=preserve
  rendering_speed: "DEFAULT",  // FLASH, TURBO, DEFAULT, QUALITY
  character_reference_images: ["https://example.com/char.jpg"],
  num_images: 1,
  magic_prompt: "AUTO",
  style_type: "AUTO"
}

Mask Requirements:

• Same dimensions as source image
• Black and white pixels only (black=areas to edit, white=areas to preserve)
• Black area must be at least 10% of total image
• Supported formats: PNG, JPEG, WebP

ideogram_describe

Generate text descriptions from images.

{
  image: "https://example.com/photo.jpg",  // URL, file path, or base64
  describe_model_version: "V_3"  // "V_2" or "V_3" (default)
}
// Returns: array of text descriptions

ideogram_upscale

Upscale images to higher resolution.

{
  image: "https://example.com/photo.jpg",
  prompt: "High detail landscape",  // Optional guided upscaling
  resemblance: 70,  // 0-100: similarity to original (default 50)
  detail: 80,       // 0-100: detail enhancement level (default 50)
  magic_prompt: "ON",
  num_images: 1,
  save_locally: true
}

ideogram_remix

Remix images with a new text prompt.

{
  image: "https://example.com/photo.jpg",
  prompt: "Transform into a watercolor painting",
  image_weight: 60,  // 0-100: influence of original image (default 50)
  aspect_ratio: "16x9",
  rendering_speed: "QUALITY",
  style_type: "FICTION",
  character_reference_images: ["https://example.com/char.jpg"],
  save_locally: true
}

ideogram_reframe

Extend images to new resolutions via intelligent outpainting.

{
  image: "https://example.com/square-photo.jpg",
  resolution: "1920x1080",  // Target resolution (required)
  rendering_speed: "DEFAULT",
  num_images: 1,
  save_locally: true
}

ideogram_replace_background

Replace image backgrounds while preserving foreground subjects.

{
  image: "https://example.com/portrait.jpg",
  prompt: "A tropical beach at sunset",  // Describe the new background
  magic_prompt: "ON",
  rendering_speed: "QUALITY",
  num_images: 4,
  save_locally: true
}
// No mask needed - AI auto-detects foreground

ideogram_generate_async

Queue generation requests for background processing.

{
  prompt: "A complex scene with many details",
  num_images: 8
}
// Returns immediately with prediction_id
// Poll with ideogram_get_prediction

ideogram_get_prediction

Check status and retrieve results of async requests.

{
  prediction_id: "pred_abc123..."
}
// Returns: status (queued/processing/completed/failed)
// When completed: includes images and cost

ideogram_cancel_prediction

Cancel queued async requests (before processing starts).

{
  prediction_id: "pred_abc123..."
}
// Only works for predictions in 'queued' status

Cost Tracking

All generation responses include estimated cost information:

{
  "total_cost": {
    "credits_used": 8,
    "estimated_usd": 0.08,
    "note": "Cost estimate based on known Ideogram pricing"
  }
}

Note: Costs are estimated locally based on known pricing. The Ideogram API does not return actual cost information.

Development

# Development with hot reload
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type checking
npm run typecheck

# Lint
npm run lint

# Format code
npm run format

# Test with MCP Inspector
npm run inspect

Project Structure

ideogram-mcp-server/
├── src/
│   ├── index.ts          # Entry point
│   ├── server.ts         # MCP server setup
│   ├── config/           # Configuration
│   ├── services/         # Core services
│   │   ├── ideogram.client.ts    # API client
│   │   ├── cost.calculator.ts    # Cost estimation
│   │   ├── prediction.store.ts   # Async job queue
│   │   └── storage.service.ts    # Local file storage
│   ├── tools/            # MCP tools (10 tools)
│   │   ├── generate.ts
│   │   ├── generate-async.ts
│   │   ├── edit.ts
│   │   ├── describe.ts
│   │   ├── upscale.ts
│   │   ├── remix.ts
│   │   ├── reframe.ts
│   │   ├── replace-background.ts
│   │   ├── get-prediction.ts
│   │   └── cancel-prediction.ts
│   ├── types/            # TypeScript types
│   └── utils/            # Utilities
├── docs/                 # Additional documentation
├── dist/                 # Built output
└── package.json

Security

• API keys are passed via environment variables, never stored in code
• All inputs validated with Zod schemas
• File operations restricted to configured directories
• No sensitive data logged

Contributing

Contributions are welcome! Please read our Contributing Guide for details on:

• Development setup
• Coding standards
• Testing requirements
• Pull request process

Quick start:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE for details.

Star History


Resources

• API Reference - Complete documentation for all 10 tools
• Ideogram API Documentation
• Model Context Protocol
• MCP SDK Documentation
• Claude Desktop MCP Guide

---

Built with love for the AI developer community