OpenAI Image Generation MCP Server

A Model Context Protocol (MCP) server that provides image generation capabilities using OpenAI's gpt-image-1 model. Compatible with Claude Code and other MCP clients.

Features

• Generate high-quality images using OpenAI's gpt-image-1 model
• Support for multiple image sizes (1024x1024, 1792x1024, 1024x1792)
• Multiple configuration methods for API keys
• Base64 image data handling and file saving
• Comprehensive error handling and validation

Installation

1. Clone this repository:

   git clone https://github.com/Maxteabag/openai-image-mcp-server.git
   cd openai-image-mcp-server

2. Install dependencies:

   pip install -r requirements.txt

3. Configure your OpenAI API key (see Configuration section)

Configuration

The server supports multiple methods to configure your OpenAI API key:

Method 1: Environment Variable (Recommended)

export OPENAI_API_KEY="your_openai_api_key_here"

Method 2: .env File

Create a .env file in the server directory:

OPENAI_API_KEY=your_openai_api_key_here

Method 3: Config File

Create ~/.config/openai-image-mcp/config.json:

{
  "openai_api_key": "your_openai_api_key_here"
}

Or create a local config.json file in the server directory.

Usage with Claude Code

Add this MCP server to Claude Code:

# Make the server executable
chmod +x server.py

# Add to Claude Code (replace with your actual path)
claude mcp add-json --scope user openai-image '{
  "command": "python3",
  "args": ["/path/to/openai-image-mcp-server/server.py"],
  "env": {
    "OPENAI_API_KEY": "your_openai_api_key_here"
  }
}'

# Verify connection
claude mcp list

Getting an OpenAI API Key

1. Visit OpenAI Platform
2. Create account or sign in
3. Generate a new API key
4. Important: Verify your organization for gpt-image-1 model access:
   • Go to Organization Settings
   • Click "Verify Organization"
   • Wait up to 15 minutes for access to propagate
5. Ensure sufficient credits for image generation

Tools

generate_image

Generate an image using OpenAI's gpt-image-1 model.

Parameters:

• prompt (required): Detailed prompt describing the image to generate
• size (optional): Image size - "1024x1024", "1792x1024", or "1024x1792" (default: "1024x1024")
• filename (optional): Output filename for the generated image (default: "generated_image.png")

Returns:

• Text description of the generation result
• Base64-encoded image resource

Example in Claude Code:

Generate an image of a serene mountain landscape at sunset with a crystal clear lake, save it as mountain_sunset.png

Running Directly

python server.py

The server listens for MCP protocol messages via stdio.

API Reference

This server implements OpenAI's image generation API:

curl -X POST "https://api.openai.com/v1/images/generations" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-type: application/json" \
    -d '{
        "model": "gpt-image-1",
        "prompt": "your detailed prompt here",
        "size": "1024x1024"
    }'

Error Handling

The server handles various conditions:

• Missing/invalid API key with helpful configuration guidance
• Invalid prompts and parameters
• API rate limits and network timeouts
• Organization verification requirements

Troubleshooting

"OpenAI API key not found" Error

Configure your API key using one of the methods above. The server checks:

1. OPENAI_API_KEY environment variable
2. .env file in server directory
3. Config files at ~/.config/openai-image-mcp/config.json or ./config.json

Permission Errors

chmod +x server.py

Module Import Errors

pip install -r requirements.txt

Requirements

• Python 3.7+
• OpenAI API key with gpt-image-1 model access
• Dependencies: httpx, python-dotenv, mcp

Contributing

Contributions welcome! This project is designed for publication on Smithery.ai.

License

MIT License