Metadata-Version: 2.4
Name: universal-image-mcp
Version: 0.1.0
Summary: Generic MCP server for image generation supporting AWS Bedrock, OpenAI, and Google Gemini
Author-email: Manu Mishra <manumishra@example.com>
License: MIT
License-File: LICENSE
Keywords: aws,gemini,image-generation,llm,mcp,openai
Requires-Python: >=3.11
Requires-Dist: boto3>=1.35.0
Requires-Dist: fastmcp>=2.14.4
Requires-Dist: google-genai>=1.7.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pillow>=12.1.0
Requires-Dist: requests>=2.31.0
Provides-Extra: test
Requires-Dist: pytest-mock>=3.12; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# Universal Image MCP - Multi-Provider AI Image Generation Server for Claude Desktop & MCP Clients

> **Universal MCP server for AI image generation** supporting AWS Bedrock (Nova Canvas), OpenAI (GPT Image, DALL-E), and Google Gemini (Imagen 4). Generate, transform, and edit images using multiple AI models through a single Model Context Protocol interface.

[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)

## What is Universal Image MCP?

Universal Image MCP is a **Model Context Protocol (MCP) server** that provides unified access to multiple AI image generation providers. Whether you're using **Claude Desktop**, **Kiro IDE**, or any MCP-compatible client, this server lets you generate and transform images using:

- **AWS Bedrock** - Amazon Nova Canvas for enterprise-grade image generation
- **OpenAI** - GPT Image 1.5, ChatGPT Image, DALL-E models
- **Google Gemini** - Gemini 2.5 Flash Image, Imagen 4, Imagen 4 Ultra

Perfect for developers building AI applications, content creators, and anyone needing programmatic access to multiple image generation APIs through a single interface.

## Example Outputs

Comparison of architecture diagrams generated by different models using this MCP server:

| Style | Model | Output |
|-------|-------|--------|
| **Technical Diagram** | OpenAI `gpt-image-1.5` | ![OpenAI Technical](images/universal-image-mcp-architecture.png) |
| **Technical Diagram** | Google `gemini-2.5-flash-image` | ![Gemini Technical](images/universal-image-mcp-architecture-gemini.png) |
| **Technical Diagram** | AWS `amazon.nova-canvas-v1:0` | ![Nova Technical](images/universal-image-mcp-architecture-nova.png) |
| **3D Clay Art** | Google `gemini-2.5-flash-image` | ![Gemini Clay](images/universal-image-mcp-architecture-clay-gemini.png) |
| **3D Clay Art** | OpenAI `gpt-image-1.5` | ![OpenAI Clay](images/universal-image-mcp-architecture-clay-openai.png) |
| **3D Clay Art** | AWS `amazon.nova-canvas-v1:0` | ![Nova Clay](images/universal-image-mcp-architecture-clay-nova.png) |

<details>
<summary>View Prompt Used</summary>

**Technical Diagram Prompt:**
```
Technical architecture diagram of a Universal Image MCP Server system. The diagram shows:

Top layer: MCP Client (Claude Desktop, Kiro IDE) connecting via Model Context Protocol

Middle layer: Universal Image MCP Server (FastMCP) with three main components:
1. Server Module (server.py) - handles list_models, generate_image, transform_image, prompt_guide tools
2. Provider Module (providers.py) - manages lazy initialization and provider abstraction
3. Configuration - environment variables for ENABLE_AWS, ENABLE_OPENAI, ENABLE_GEMINI

Bottom layer: Three provider boxes side by side:
- AWS Bedrock (boto3) - Amazon Nova Canvas, with AWS credentials and region config
- OpenAI API - GPT Image 1.5, ChatGPT Image Latest, with API key
- Google Gemini API - Gemini 2.5 Flash, Imagen 4, with API key

Data flow arrows showing:
- Client sends tool requests to Server
- Server routes to appropriate Provider based on model_id
- Providers make API calls to their respective services
- Image data flows back through the chain

Clean, professional software architecture diagram style with boxes, arrows, and labels. Use blue and gray color scheme. Modern technical documentation aesthetic. Isometric or layered view showing clear separation of concerns.
```

**3D Clay Art Prompt:**
```
Same technical architecture content as above, but rendered in:

3D clay art style with soft rounded shapes, pastel colors, cute minimalist aesthetic, soft studio lighting, clean composition with depth and shadows.
```

*Note: 3D Clay Art versions used `s3tablearch.png` as a reference image for style guidance.*

</details>

## Key Features

- 🔄 **Multi-Provider Support** - Switch between AWS Bedrock, OpenAI, and Google Gemini seamlessly
- 🚀 **Dynamic Model Discovery** - Automatically fetches latest available models from each provider API
- ⚡ **Lazy Initialization** - Provider clients load only when needed for optimal performance
- 🎨 **Reference Image Support** - Generate new images based on existing image styles
- 📐 **Configurable Dimensions** - Custom width/height for supported AI models
- 📚 **Built-in Prompt Guide** - Best practices for writing effective image generation prompts
- 🔌 **MCP Protocol** - Works with Claude Desktop, Kiro IDE, and all MCP-compatible clients
- 🐍 **Python 3.11+** - Modern Python with type hints and async support

## Quick Start Installation

Install via pip:

```bash
pip install universal-image-mcp
```

Or use with uvx (recommended for MCP servers):

```bash
uvx universal-image-mcp@latest
```

## MCP Server Configuration

### For Claude Desktop

Add to your Claude Desktop MCP configuration file:

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

```json
{
  "mcpServers": {
    "universal-image-mcp": {
      "command": "uvx",
      "args": ["universal-image-mcp@latest"],
      "env": {
        "ENABLE_AWS": "true",
        "AWS_PROFILE": "default",
        "AWS_REGION": "us-east-1",
        
        "ENABLE_OPENAI": "true",
        "OPENAI_API_KEY": "sk-...",
        
        "ENABLE_GEMINI": "true",
        "GEMINI_API_KEY": "..."
      }
    }
  }
}
```

### For Kiro IDE

Add to `~/.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "universal-image-mcp": {
      "command": "uvx",
      "args": ["universal-image-mcp@latest"],
      "env": {
        "ENABLE_AWS": "true",
        "ENABLE_OPENAI": "true",
        "OPENAI_API_KEY": "sk-...",
        "ENABLE_GEMINI": "true",
        "GEMINI_API_KEY": "..."
      }
    }
  }
}
```

## Getting API Keys and Credentials

Before using this MCP server, you'll need to obtain credentials for the providers you want to use.

### AWS Bedrock Setup

AWS Bedrock uses your local AWS credentials. You have several options:

1. **AWS CLI Configuration** (Recommended)
   - Install the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
   - Run `aws configure` and provide your access key, secret key, and region
   - Official guide: [AWS CLI Configuration](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html)

2. **AWS Credentials File**
   - Create `~/.aws/credentials` with your access keys
   - Create `~/.aws/config` with your region settings
   - Official guide: [Shared Config and Credentials Files](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)

3. **Environment Variables**
   - Set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION`
   - Official guide: [AWS CLI Authentication](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-authentication.html)

**Getting AWS Access Keys:**
- Sign in to the [AWS Console](https://console.aws.amazon.com/)
- Navigate to IAM → Users → Your User → Security Credentials
- Create a new access key under "Access keys"
- Ensure your IAM user has permissions for Bedrock (e.g., `AmazonBedrockFullAccess` policy)

### OpenAI API Key

1. **Create an OpenAI Account**
   - Visit [OpenAI Platform](https://platform.openai.com/)
   - Sign up or log in to your account

2. **Generate API Key**
   - Go to [API Keys page](https://platform.openai.com/account/api-keys)
   - Click "Create new secret key"
   - Give it a descriptive name (optional)
   - Copy the key immediately (you won't be able to see it again)

3. **Add Billing Information**
   - OpenAI requires payment information to use the API
   - Navigate to [Billing](https://platform.openai.com/account/billing) to add payment details

**Official Documentation:** [OpenAI Quickstart Guide](https://platform.openai.com/docs/quickstart)

### Google Gemini API Key

1. **Get a Gemini API Key**
   - Visit [Google AI Studio](https://ai.google.dev/gemini-api/docs/api-key)
   - Sign in with your Google account
   - Click "Get API Key" or "Create API Key"
   - Create a new project or select an existing one
   - Copy your API key

2. **Alternative: Google Cloud API Key**
   - For production use, you can use [Vertex AI on Google Cloud](https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys)
   - This provides more enterprise features and billing controls

**Official Documentation:** [Gemini API Quickstart](https://ai.google.dev/gemini-api/docs/quickstart)

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `ENABLE_AWS` | No | Enable AWS Bedrock provider (`true`/`false`, default: `false`) |
| `AWS_PROFILE` | No | AWS profile name (default, SSO, or named profile) |
| `AWS_REGION` | No | AWS region (default: `us-east-1`) |
| `ENABLE_OPENAI` | No | Enable OpenAI provider (`true`/`false`, default: `false`) |
| `OPENAI_API_KEY` | If OpenAI enabled | OpenAI API key from [platform.openai.com](https://platform.openai.com/account/api-keys) |
| `ENABLE_GEMINI` | No | Enable Google Gemini provider (`true`/`false`, default: `false`) |
| `GEMINI_API_KEY` | If Gemini enabled | Google Gemini API key from [Google AI Studio](https://ai.google.dev/gemini-api/docs/api-key) |

## API Reference - MCP Tools

### list_models()

**List all available AI image generation models** from enabled providers. Models are fetched dynamically from each provider's API with deprecated models automatically filtered.

**Returns**: Formatted list of model IDs compatible with `generate_image()` and `transform_image()`

**Example models**:
- AWS: `amazon.nova-canvas-v1:0`
- OpenAI: `gpt-image-1.5`, `chatgpt-image-latest`
- Gemini: `models/gemini-2.5-flash-image`, `models/imagen-4.0-generate-001`

### generate_image(prompt, model_id, output_path, reference_image?, width?, height?)

**Generate AI images from text prompts** using any supported model.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `prompt` | Yes | - | Detailed text description of the image. Be specific about subject, style, lighting, colors, composition, and mood. |
| `model_id` | Yes | - | Model ID from `list_models()`. Examples: `amazon.nova-canvas-v1:0`, `gpt-image-1.5`, `models/gemini-2.5-flash-image` |
| `output_path` | Yes | - | File path to save the generated image. Parent directories created automatically. |
| `reference_image` | No | None | Path to reference image for style/content guidance |
| `width` | No | 1024 | Image width in pixels. Note: Some models only support specific sizes. |
| `height` | No | 1024 | Image height in pixels. Note: Some models only support specific sizes. |

### transform_image(image_path, prompt, model_id, output_path)

**Transform and edit existing images** using AI-powered modifications based on text prompts.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `image_path` | Yes | Path to source image to transform (PNG, JPEG, etc.) |
| `prompt` | Yes | AI transformation instructions (e.g., "Make it black and white", "Add a rainbow", "Convert to watercolor style") |
| `model_id` | Yes | Model ID from `list_models()` |
| `output_path` | Yes | File path to save the transformed image |

**Use cases**: Image editing, style transfer, AI-powered photo manipulation, artistic transformations

### prompt_guide()

**Get AI prompt engineering best practices** for image generation. Returns comprehensive guidelines covering:
- Prompt structure (Subject + Details + Style + Lighting + Mood + Composition)
- Specific vs generic descriptions
- Style, lighting, and mood keywords
- Example prompts for different use cases

## Supported AI Image Models

All models are discovered dynamically. Use `list_models()` to see current options.

### AWS Bedrock Models
- **Amazon Nova Canvas** (`amazon.nova-canvas-v1:0`) - Enterprise-grade image generation with text and image input support

### OpenAI Models
- **GPT Image 1.5** (`gpt-image-1.5`) - Latest OpenAI image generation model
- **ChatGPT Image Latest** (`chatgpt-image-latest`) - ChatGPT-integrated image generation

### Google Gemini Models
- **Gemini 2.5 Flash Image** (`models/gemini-2.5-flash-image`) - Fast, efficient image generation
- **Gemini 3 Pro Image** (`models/gemini-3-pro-image-preview`) - Advanced image generation capabilities
- **Imagen 4** (`models/imagen-4.0-generate-001`) - Google's state-of-the-art image model
- **Imagen 4 Ultra** (`models/imagen-4.0-ultra-generate-001`) - Highest quality Imagen model
- **Imagen 4 Fast** (`models/imagen-4.0-fast-generate-001`) - Optimized for speed

## Use Cases

- **AI Application Development** - Integrate multiple image generation providers into your apps
- **Content Creation** - Generate marketing materials, social media content, illustrations
- **Prototyping & Design** - Quickly visualize concepts and design ideas
- **Image Editing Automation** - Batch process and transform images with AI
- **Research & Experimentation** - Compare outputs across different AI models
- **Claude Desktop Workflows** - Enhance Claude conversations with image generation
- **Developer Tools** - Build MCP-compatible tools and extensions

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

## Related Projects

- [Model Context Protocol](https://modelcontextprotocol.io) - Official MCP documentation
- [Claude Desktop](https://claude.ai/desktop) - AI assistant with MCP support
- [FastMCP](https://github.com/jlowin/fastmcp) - Python framework for building MCP servers

## Keywords

`mcp-server` `image-generation` `ai-images` `aws-bedrock` `openai` `google-gemini` `claude-desktop` `imagen` `nova-canvas` `python` `fastmcp` `model-context-protocol` `ai-art` `text-to-image` `image-transformation`

## License

MIT
