mcp-imager

A Model Context Protocol (MCP) server that provides AI image generation capabilities using multiple providers. This server enables AI assistants like Claude to generate images through a standardized interface.

Features

• Multiple Providers: Support for OpenAI GPT Image and Google Imagen 4 image generation
• Unified Interface: Single API that abstracts provider differences
• Flexible Configuration: Easy provider selection via environment variables
• Multiple Output Formats: PNG, JPEG, and WebP support
• Configurable Sizes: Small (1024x1024), medium (1024x1024), and large (1536x1024) options
• Batch Generation: Generate up to 10 images in a single request
• Error Handling: Comprehensive error handling with retry logic for transient failures

Installation

Prerequisites

• Node.js 18.0.0 or higher
• npm or another package manager

Install via npx (Recommended)

No installation required - just run directly:

npx mcp-imager

Install from Source

# Clone the repository
git clone https://github.com/bannsec/mcp-imager.git
cd mcp-imager

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Environment Variables

Create a .env file or set environment variables directly:

| Variable | Description | Required | |----------|-------------|----------| | OPENAI_API_KEY | Your OpenAI API key for GPT Image models | At least one provider key required | | GOOGLE_API_KEY | Your Google AI API key for Imagen models | At least one provider key required | | GEMINI_API_KEY | Alternative to GOOGLE_API_KEY | At least one provider key required | | DEFAULT_PROVIDER | Default provider (google or openai) | No (defaults to google) |

Getting API Keys

• OpenAI: Get your API key at https://platform.openai.com/api-keys
• Google AI: Get your API key at https://aistudio.google.com/apikey

Example .env File

# Copy from .env.example and fill in your keys
OPENAI_API_KEY=sk-your-openai-api-key-here
GOOGLE_API_KEY=your-google-api-key-here
DEFAULT_PROVIDER=openai

Claude Code Configuration

To use with Claude Code, add the MCP server using one of these methods:

Option 1: Claude CLI (Recommended)

# Add with environment variables (user scope - available across all projects)
claude mcp add --transport stdio --scope user \
  --env OPENAI_API_KEY=sk-your-openai-api-key \
  --env GOOGLE_API_KEY=your-google-api-key \
  -- mcp-imager npx -y mcp-imager

# Or for project-local scope (default)
claude mcp add --transport stdio \
  --env OPENAI_API_KEY=sk-your-openai-api-key \
  --env GOOGLE_API_KEY=your-google-api-key \
  -- mcp-imager npx -y mcp-imager

You can manage the server with these commands:

# List all configured MCP servers
claude mcp list

# Get details for the mcp-imager server
claude mcp get mcp-imager

# Remove the server
claude mcp remove mcp-imager

Option 2: Global Configuration (~/.claude/claude_code_config.json)

{
  "mcpServers": {
    "mcp-imager": {
      "command": "npx",
      "args": ["-y", "mcp-imager"],
      "env": {
        "OPENAI_API_KEY": "sk-your-openai-api-key",
        "GOOGLE_API_KEY": "your-google-api-key",
        "DEFAULT_PROVIDER": "openai"
      }
    }
  }
}

Option 3: Project Configuration (.mcp.json in project root)

{
  "mcpServers": {
    "mcp-imager": {
      "command": "npx",
      "args": ["-y", "mcp-imager"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
        "GOOGLE_API_KEY": "${GOOGLE_API_KEY}"
      }
    }
  }
}

Other MCP Clients

The server uses STDIO transport and is compatible with any MCP client. Start it with:

node dist/index.js

Or use the development mode:

npm run dev

Available Tools

1. generate_image

Generate images using AI providers.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | prompt | string | Yes | Text description of the image to generate | | provider | "google" | "openai" | No | Provider to use (defaults to configured default) | | size | "small" | "medium" | "large" | No | Image size (default: "medium") | | numberOfImages | number (1-10) | No | Number of images to generate (default: 1) | | format | "png" | "jpeg" | "webp" | No | Output format (default: "png") | | aspectRatio | "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | No | Aspect ratio for image (default: "1:1") |

Size Dimensions:

• small: 1024x1024 pixels
• medium: 1024x1024 pixels
• large: 1536x1024 pixels

Example Usage (in Claude Code or MCP client):

Generate an image of a sunset over mountains

Generate 3 large JPEG images of a futuristic city using OpenAI

2. list_providers

List all available image generation providers and their configuration status.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | detailed | boolean | No | Return detailed provider information (default: false) |

Example Output:

- Google Imagen 4 (google): Ready
- OpenAI GPT Image (openai): Ready

Default provider: google

3. get_provider_info

Get detailed information about a specific image generation provider.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | provider | "google" | "openai" | Yes | The provider to get information about |

Example Output:

{
  "id": "openai",
  "name": "OpenAI GPT Image",
  "model": "gpt-image-1",
  "description": "Generate images using OpenAI's gpt-image-1 model with high quality and creative capabilities",
  "supportedSizes": ["small", "medium", "large"],
  "supportedFormats": ["png", "jpeg", "webp"],
  "maxPromptLength": 32000
}

4. ping

Test tool to verify the MCP server is running and responsive.

Example Output:

mcp-imager v1.0.0 is running

Supported Providers

OpenAI GPT Image

• Model: gpt-image-1
• Max Prompt Length: 32,000 characters
• Supported Formats: PNG, JPEG, WebP
• Features: High quality, creative image generation with revised prompt support

Google Imagen 4

• Model: imagen-4.0-generate-001
• Max Prompt Length: 480 characters
• Supported Formats: PNG, JPEG, WebP
• Features: High-quality image generation with aspect ratio support

Error Handling

The server handles various error scenarios:

• Rate Limiting: Automatic retry with exponential backoff
• Network Errors: Retryable with configurable timeouts
• Content Policy Violations: Clear error messages for blocked content
• Authentication Errors: Helpful messages for invalid API keys
• Invalid Prompts: Validation for empty or too-long prompts

Development

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

Project Structure

mcp-imager/
├── src/
│   ├── index.ts          # Main MCP server entry point
│   ├── config/           # Configuration management
│   ├── providers/        # Provider implementations
│   │   ├── openai.ts     # OpenAI provider client
│   │   ├── google.ts     # Google Imagen provider client
│   │   └── index.ts      # Provider factory
│   ├── handlers/         # Tool handlers
│   ├── errors/           # Error types and handling
│   └── types/            # TypeScript type definitions
├── dist/                 # Compiled JavaScript (after build)
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request at github.com/bannsec/mcp-imager.