OpenAI Image 1 Ideogram MCP

Overview

OpenAI Image 1 Ideogram MCP is an enterprise-grade Model Context Protocol (MCP) server that provides seamless integration with Ideogram's v3.0 API. This professional-grade solution enables advanced AI image generation capabilities with sophisticated style control, rendering optimization, and enhanced quality output for production environments.

Built with TypeScript and modern development practices, this MCP server offers robust error handling, comprehensive validation, and enterprise-ready features for organizations requiring reliable AI image generation services.

Model Context Protocol (MCP) Integration

This server implements the Model Context Protocol (MCP) standard, enabling seamless integration with AI assistants and applications. MCP provides a standardized way for AI models to access external tools and services, making this Ideogram integration immediately compatible with:

Claude Desktop: Direct integration through MCP configuration
Custom AI Applications: Any MCP-compatible client
Development Environments: Local and cloud-based AI development setups
Enterprise AI Platforms: Scalable deployment across organizations

The MCP architecture ensures secure, reliable, and standardized communication between AI models and the Ideogram v3.0 API, providing enterprise-grade image generation capabilities with professional oversight and control.

📚 Complete Documentation Suite

This repository includes comprehensive documentation for setting up AI-powered development environments:

🚀 Complete Installation & Setup Guide

Quick Links

Ideogram MCP Server Installation - This MCP server setup guide
Agent Zero Installation - Docker-based AI development platform
Cursor IDE Setup - AI-powered code editor
Windsurf IDE Installation - First agentic IDE
Claude Desktop Setup - MCP integration guide
Augment Code Platform - Advanced AI coding assistant
MCP Configuration Guide - Model Context Protocol setup
API Keys Management - Secure authentication setup
Troubleshooting Guide - Common issues and solutions

Core Features

Advanced Image Generation

Ideogram v3.0 Integration: Full support for the latest Ideogram API with enhanced capabilities
Style Reference System: Upload up to 3 reference images or utilize 8-character hexadecimal style codes
Rendering Optimization: Configurable rendering speeds (TURBO, DEFAULT, QUALITY) for performance tuning
Enhanced Realism: State-of-the-art photorealistic image generation with superior quality
Professional Graphics: Enterprise-grade text rendering and creative design capabilities
Magic Prompt Enhancement: AI-powered prompt optimization for improved results

Production-Ready Capabilities

Batch Processing: Generate 1-8 images per request for efficient workflows
Flexible Aspect Ratios: Support for 15 standard aspect ratios including 1x1, 16x9, 4x3, and more
Resolution Control: Access to 69+ resolution options for diverse output requirements
Style Management: Advanced style code system with access to 4.3 billion preset styles
Content Filtering: Negative prompt support for precise content exclusion
Reproducible Generation: Seed-based control for consistent and repeatable results

Installation & Setup

Prerequisites

Node.js: Version 18.0.0 or higher
npm: Latest stable version
Ideogram API Key: Obtain from Ideogram API Management

Package Installation

Install the package via npm:

npm install @lyoncrypt/openai-image-1-ideogram-mcp

Claude Desktop Integration

Configure your Claude Desktop MCP settings by adding the following to your configuration file:

{
  "mcpServers": {
    "openai-image-1-ideogram": {
      "command": "npx",
      "args": [
        "@lyoncrypt/openai-image-1-ideogram-mcp"
      ],
      "env": {
        "IDEOGRAM_API_KEY": "your_ideogram_api_key_here"
      }
    }
  }
}

Environment Configuration

Set up your environment variables:

# Required: Ideogram API Key
export IDEOGRAM_API_KEY="your_ideogram_api_key"

# Optional: Custom output directory
export OUTPUT_DIR="./generated-images"

# Optional: Default filename prefix
export BASE_FILENAME="ai-generated-image"

API Reference

`generate_image`

The primary tool for generating high-quality images using Ideogram's v3.0 API with comprehensive parameter control.

Method Signature

generate_image(parameters: GenerateImageParams): Promise<GenerationResult>

Parameters

Parameter	Type	Description	Required	Default
`prompt`	`string`	Primary image generation prompt (English recommended)	✅	-
`aspect_ratio`	`AspectRatio`	Image aspect ratio from supported options	❌	`1x1`
`resolution`	`string`	Specific resolution (see supported resolutions)	❌	Auto
`seed`	`integer`	Deterministic seed for reproducible results (0-2147483647)	❌	Random
`magic_prompt`	`MagicPrompt`	AI prompt enhancement: `AUTO`\|`ON`\|`OFF`	❌	`AUTO`
`rendering_speed`	`RenderingSpeed`	Quality vs speed: `TURBO`\|`DEFAULT`\|`QUALITY`	❌	`DEFAULT`
`style_codes`	`string[]`	Array of 8-character hexadecimal style codes	❌	`[]`
`style_type`	`StyleType`	Style category: `AUTO`\|`GENERAL`\|`REALISTIC`\|`DESIGN`	❌	`AUTO`
`style_reference`	`StyleReference`	Advanced style reference configuration	❌	`null`
`negative_prompt`	`string`	Content exclusion specifications	❌	`""`
`num_images`	`integer`	Batch size for generation (1-8)	❌	`1`
`output_dir`	`string`	Local storage directory path	❌	`"docs"`
`base_filename`	`string`	File naming prefix	❌	`"ideogram-image"`
`blur_mask`	`boolean`	Apply artistic edge blur effect	❌	`false`

Style Reference Object

{
  urls?: string[];        // Up to 3 reference image URLs
  style_code?: string;    // 8-character style code
  random_style?: boolean; // Use random style from library
}

Implementation Examples

Basic Image Generation

Standard image generation with quality optimization:

{
  "prompt": "Professional corporate office environment with modern design elements",
  "aspect_ratio": "16x9",
  "rendering_speed": "QUALITY",
  "style_type": "REALISTIC"
}

Advanced Style Reference Implementation

Utilizing style references for brand consistency:

{
  "prompt": "Modern minimalist logo design for technology company",
  "style_reference": {
    "urls": ["https://example.com/brand-reference.jpg"],
    "random_style": false
  },
  "style_type": "DESIGN",
  "num_images": 4,
  "negative_prompt": "cluttered, busy, complex"
}

Enterprise Batch Processing

High-volume generation with reproducible results:

{
  "prompt": "Professional product photography for e-commerce catalog",
  "rendering_speed": "QUALITY",
  "style_type": "REALISTIC",
  "negative_prompt": "blurry, low resolution, amateur",
  "seed": 12345,
  "num_images": 8,
  "aspect_ratio": "1x1"
}

Creative Design Workflow

Advanced creative generation with style codes:

{
  "prompt": "Artistic poster design with typography and geometric elements",
  "style_codes": ["A1B2C3D4", "E5F6G7H8"],
  "style_type": "DESIGN",
  "magic_prompt": "ON",
  "rendering_speed": "QUALITY",
  "blur_mask": true
}

Development Guide

Development Prerequisites

Node.js: Version 18.0.0 or higher
TypeScript: Version 5.0.0 or higher
Git: Latest stable version
Ideogram API Key: Valid API credentials

Local Development Setup

Clone and configure the development environment:

git clone https://github.com/Thelyoncrypt/openai-image-1-ideogram-mcp.git
cd openai-image-1-ideogram-mcp
npm install
cp .env.example .env
# Configure your API key in .env file

Build Process

Compile TypeScript to JavaScript:

npm run build

Development Workflow

Enable watch mode for continuous compilation:

npm run watch

Quality Assurance

Run the complete test suite:

npm test
npm run lint

Project Architecture

openai-image-1-ideogram-mcp/
├── src/                          # Source code directory
│   ├── types/
│   │   └── ideogram.ts          # TypeScript type definitions
│   ├── tools/
│   │   └── generate-image.ts    # Core image generation tool
│   ├── utils/
│   │   └── validation.ts        # Input validation utilities
│   ├── ideogram-client.ts       # Ideogram API client implementation
│   ├── server.ts               # MCP server configuration
│   └── index.ts                # Application entry point
├── dist/                        # Compiled JavaScript output
├── docs/                        # Generated images storage
├── package.json                 # Package configuration
├── tsconfig.json               # TypeScript configuration
├── .env.example                # Environment template
├── .gitignore                  # Git ignore rules
├── LICENSE                     # MIT license
├── CHANGELOG.md               # Version history
└── README.md                  # Project documentation

Configuration Reference

Supported Aspect Ratios

Category	Ratios	Use Cases
Square	`1x1`	Social media posts, avatars, logos
Landscape	`16x9`, `4x3`, `21x9`, `3x2`, `5x4`, `3x1`, `2x1`	Presentations, banners, headers
Portrait	`9x16`, `3x4`, `9x21`, `2x3`, `4x5`, `1x3`, `1x2`	Mobile content, posters, stories

Rendering Performance Options

Speed	Quality	Use Case	Typical Generation Time
TURBO	Good	Rapid prototyping, previews	~5-10 seconds
DEFAULT	High	Standard production use	~15-30 seconds
QUALITY	Premium	Final deliverables, print	~30-60 seconds

Style Type Categories

AUTO: Intelligent style selection based on prompt content
GENERAL: Versatile style suitable for most applications
REALISTIC: Photorealistic rendering for authentic imagery
DESIGN: Optimized for graphics, logos, and creative designs

Contributing

We welcome contributions from the community. Please follow our contribution guidelines:

Development Process

Fork the repository to your GitHub account
Clone your fork locally
Create a feature branch (git checkout -b feature/amazing-feature)
Implement your changes with appropriate tests
Commit your changes (git commit -m 'Add amazing feature')
Push to your branch (git push origin feature/amazing-feature)
Submit a Pull Request with detailed description

Code Standards

Follow TypeScript best practices
Maintain test coverage above 80%
Use conventional commit messages
Update documentation for new features

License

This project is licensed under the MIT License - see the LICENSE file for complete details.

Resources & Documentation

Ideogram v3.0 API Documentation
Model Context Protocol Specification
Claude Desktop Integration Guide
TypeScript Documentation

Release Notes

Version 1.0.0 - Initial Release

New Features:

Complete Ideogram v3.0 API integration
Advanced style reference system with image upload support
Configurable rendering speed optimization
Enterprise-grade error handling and validation
Professional TypeScript implementation with full type safety
Comprehensive MCP server with robust tool definitions

Technical Improvements:

Modern ES2022 TypeScript architecture
Axios-based HTTP client with retry logic
Comprehensive input validation and sanitization
Modular design with separation of concerns
Production-ready logging and monitoring hooks

Developed by Lyoncrypt | Powered by Ideogram v3.0 API

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
docs		docs
src		src
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
MCP BANNER.png		MCP BANNER.png
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

Thelyoncrypt/openai-image-1-ideogram-mcp

Folders and files

Latest commit

History

Repository files navigation

OpenAI Image 1 Ideogram MCP

Overview

Model Context Protocol (MCP) Integration

📚 Complete Documentation Suite

Quick Links

Core Features

Advanced Image Generation

Production-Ready Capabilities

Installation & Setup

Prerequisites

Package Installation

Claude Desktop Integration

Environment Configuration

API Reference

generate_image

Method Signature

Parameters

Style Reference Object

Implementation Examples

Basic Image Generation

Advanced Style Reference Implementation

Enterprise Batch Processing

Creative Design Workflow

Development Guide

Development Prerequisites

Local Development Setup

Build Process

Development Workflow

Quality Assurance

Project Architecture

Configuration Reference

Supported Aspect Ratios

Rendering Performance Options

Style Type Categories

Contributing

Development Process

Code Standards

License

Resources & Documentation

Release Notes

Version 1.0.0 - Initial Release

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`generate_image`

Packages