GPT-Image-1 MCP Server

A Model Context Protocol (MCP) server that provides image generation, editing, and management capabilities using OpenAI's GPT-Image-1 model.

Features

• Image Generation: Generate high-quality images from text prompts
• Image Editing: Edit existing images with new prompts
• Image Management: Store, retrieve, and manage generated images
• History Tracking: Track all image generations with metadata
• Comprehensive Logging: Full logging and error handling
• TypeScript Support: Fully typed with TypeScript

Installation

Via npm (Recommended)

npm install -g @graisol/gpt-image-mcp

From Source

1. Clone the repository:

git clone https://github.com/GRAIsol/gpt-image-mcp.git
cd gpt-image-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Command Line Usage

# Using npm global installation
gpt-image-mcp --api-key your_openai_api_key_here

# Using npx
npx @graisol/gpt-image-mcp --api-key your_openai_api_key_here

# Show help
gpt-image-mcp --help

Environment Variables (Optional)

You can also use environment variables for configuration:

# Required (if not provided via --api-key)
OPENAI_API_KEY=your_openai_api_key_here

# Optional
OPENAI_ORG_ID=your_org_id_here
DEFAULT_IMAGE_SIZE=1024x1024
DEFAULT_IMAGE_QUALITY=high
DEFAULT_MODERATION=auto
IMAGE_STORAGE_PATH=./images
MAX_STORED_IMAGES=100
LOG_LEVEL=2
LOG_FILE=./logs/server.log

Usage

Development Mode

npm run dev

Production Mode

npm run build
npm start

MCP Integration

Claude Code CLI (Recommended)

If you installed the package globally via npm:

claude mcp add gpt-image-mcp gpt-image-mcp --api-key your_openai_api_key_here

Or using npx:

claude mcp add gpt-image-mcp npx @graisol/gpt-image-mcp --api-key your_openai_api_key_here

If you built from source:

claude mcp add gpt-image-mcp node /PATH/TO/YOUR/PROJECT/gpt-image-mcp/build/index.js --env OPENAI_API_KEY=your_openai_api_key_here

Replace your_openai_api_key_here with your actual OpenAI API key.

Claude Desktop Configuration

For Claude Desktop, add the following to your configuration file:

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

If you installed via npm:

{
  "mcpServers": {
    "gpt-image-1": {
      "command": "npx",
      "args": ["@graisol/gpt-image-mcp", "--api-key", "your_openai_api_key_here"]
    }
  }
}

Or using environment variables:

{
  "mcpServers": {
    "gpt-image-1": {
      "command": "npx",
      "args": ["@graisol/gpt-image-mcp"],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key_here"
      }
    }
  }
}

If you built from source:

{
  "mcpServers": {
    "gpt-image-1": {
      "command": "node",
      "args": ["/path/to/your/gpt-image-mcp/build/index.js"],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key_here"
      }
    }
  }
}

Other IDEs (VS Code, Cursor, etc.)

For other IDEs and editors, refer to their specific MCP integration documentation for JSON configuration format.

MCP Tools

generate_image

Generate images from text prompts.

Parameters:

• prompt (required): Text description of the image
• size (optional): Image size (default: 1024x1024)
• quality (optional): Image quality - 'standard' or 'hd' (default: standard)
• style (optional): Image style - 'vivid' or 'natural' (default: natural)
• response_format (optional): Response format - 'url' or 'b64_json' (default: url)
• moderation (optional): Moderation level - 'auto' or 'low' (default: auto)

Example:

{
  "prompt": "A futuristic cityscape at sunset with flying cars",
  "size": "1024x1024",
  "quality": "hd",
  "style": "vivid"
}

edit_image

Edit existing images with new prompts.

Parameters:

• image (required): Base64 encoded image or image URL
• prompt (required): Text description of desired changes
• size (optional): Output image size
• response_format (optional): Response format - 'url' or 'b64_json'
• moderation (optional): Moderation level - 'auto' or 'low'

Example:

{
  "image": "data:image/png;base64,iVBORw0KGgoAAAANS...",
  "prompt": "Add a rainbow in the sky",
  "size": "1024x1024"
}

get_image_info

Get detailed information about a generated image.

Parameters:

• image_id (required): ID of the image

Example:

{
  "image_id": "img_1640995200000_abc123def456"
}

list_generations

List recent image generations with optional filtering.

Parameters:

• limit (optional): Maximum number of results (default: 10)
• offset (optional): Number of results to skip (default: 0)
• filter (optional): Filter by prompt content

Example:

{
  "limit": 20,
  "offset": 0,
  "filter": "sunset"
}

API Response Format

All tools return responses in the following format:

{
  "content": [
    {
      "type": "text",
      "text": "JSON-formatted result"
    }
  ]
}

Supported Image Sizes

• 256x256
• 512x512
• 1024x1024 (default)
• 1792x1024
• 1024x1792
• 2048x2048
• 4096x4096

Error Handling

The server provides comprehensive error handling with detailed error messages:

• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Invalid API key
• 403 Forbidden: Access denied or organization verification required
• 404 Not Found: Model or endpoint not found
• 429 Rate Limited: Too many requests
• 500 Internal Server Error: OpenAI service temporarily unavailable

Storage

Generated images and metadata are stored locally in the configured storage directory:

• ./images/ - Default storage location
• generation_history.json - Image generation history
• {image_id}.json - Individual image metadata files
• {image_id}.png - Base64 images (if stored locally)

Logging

The server includes comprehensive logging with configurable levels:

• ERROR (0): Error messages only
• WARN (1): Warning and error messages
• INFO (2): Informational, warning, and error messages (default)
• DEBUG (3): All messages including debug information

Development

Project Structure

gpt-image-mcp/
├── src/
│   ├── types/          # TypeScript type definitions
│   ├── utils/          # Utility functions
│   │   ├── openai-client.ts
│   │   ├── image-manager.ts
│   │   └── logger.ts
│   ├── tools/          # MCP tool implementations
│   │   └── index.ts
│   └── index.ts        # Main server entry point
├── build/              # Compiled JavaScript output
├── images/             # Image storage directory
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Running Tests

npm test

License

MIT License

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions, please open an issue on the GitHub repository.