gpt-image MCP

MCP server for AI-powered image generation using OpenAI's gpt-image-1 and gpt-image-2 models with advanced text rendering and native transparency support.

Features

• Advanced text rendering with gpt-image-1 - Crisp, legible typography and logos in generated images
• Native transparency support - Built-in transparent background without post-processing
• Multi-format output (PNG, JPEG, WebP) - Flexible format options with optimized compression
• Flexible dimensions and aspect ratios - Square (1024×1024), landscape (1536×1024), and portrait (1024×1536)
• Batch image editing capabilities - Process multiple images with parallel processing
• Token-optimized MCP responses - Efficient response formats for MCP protocol limits

Installation

Recommended: Using npx

{
  "mcpServers": {
    "gpt-image-mcp": {
      "command": "npx",
      "args": ["@napolab/gpt-image-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-your-api-key"
      }
    }
  }
}

Alternative: Local Installation

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

Claude Desktop Configuration

Configure in ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "gpt-image-mcp": {
      "command": "npx",
      "args": ["@napolab/gpt-image-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-your-api-key"
      }
    }
  }
}

Configuration

Environment Variables

| Variable | Required | Default | Description | | ----------------------- | -------- | -------------------- | ------------------------------ | | OPENAI_API_KEY | Yes | - | Your OpenAI API key | | DEFAULT_OUTPUT_DIR | No | ./generated_images | Default output directory | | DEFAULT_IMAGE_SIZE | No | 1024x1024 | Default image dimensions | | DEFAULT_IMAGE_QUALITY | No | standard | Default quality (standard/hd) | | DEFAULT_OUTPUT_FORMAT | No | png | Default format (png/jpeg/webp) |

Available Tools

generate-image

Generate images using gpt-image-1 with advanced text rendering and superior instruction following.

Parameters:

| Parameter | Type | Required | Default | Description | | ------------------ | ------- | -------- | -------------------- | ------------------------------------ | | prompt | string | Yes | - | Image description (English only) | | aspect_ratio | string | No | square | "square", "landscape", or "portrait" | | quality | string | No | standard | "standard" or "hd" | | output_directory | string | No | ./generated_images | Directory to save the image | | filename | string | No | - | Custom filename | | save_to_file | boolean | No | true | Whether to save locally | | include_base64 | boolean | No | false | Include base64 in response |

Example:

await client.callTool("generate-image", {
  prompt: "A serene Japanese garden with cherry blossoms",
  aspect_ratio: "landscape",
  quality: "hd",
});

edit-image

Edit existing images with AI-powered modifications including inpainting, outpainting, style transfer, and background changes.

Parameters:

| Parameter | Type | Required | Default | Description | | ---------------------- | ------- | -------- | ------- | --------------------------------------------- | | source_image | object | Yes | - | Image input (URL, base64, or local file) | | edit_prompt | string | Yes | - | Description of desired changes (English only) | | edit_type | string | Yes | - | Type of edit to perform | | strength | number | No | 0.8 | Edit strength (0.0 to 1.0) | | preserve_composition | boolean | No | true | Maintain original composition | | output_format | string | No | png | Output format |

Edit Types:

• inpaint - Fill in or modify specific areas
• outpaint - Extend image beyond boundaries
• background_change - Replace or modify background
• style_transfer - Apply artistic styles
• object_removal - Remove unwanted objects
• variation - Create variations of original

Example:

await client.callTool("edit-image", {
  source_image: {
    type: "local",
    value: "/path/to/image.jpg",
  },
  edit_prompt: "Add a sunset sky background",
  edit_type: "background_change",
});

batch-edit

Apply the same edit to multiple images efficiently with parallel processing.

Parameters:

| Parameter | Type | Required | Default | Description | | ---------------- | ------ | -------- | ------- | ------------------------------- | | images | array | Yes | - | Array of image inputs | | edit_prompt | string | Yes | - | Edit description (English only) | | edit_type | string | Yes | - | Type of edit to apply | | batch_settings | object | No | - | Batch processing configuration |

Example:

await client.callTool("batch-edit", {
  images: [
    { type: "local", value: "/path/to/image1.jpg" },
    { type: "local", value: "/path/to/image2.jpg" },
  ],
  edit_prompt: "Apply vintage sepia filter",
  edit_type: "style_transfer",
});

Usage Examples

Basic Image Generation

// Generate a simple image
const result = await client.callTool("generate-image", {
  prompt: "A modern minimalist logo design",
  aspect_ratio: "square",
  quality: "hd",
});

console.log("Generated image:", result.data.file_path);

Advanced Options

// Generate with all parameters
const result = await client.callTool("generate-image", {
  prompt: "Professional product photography of a smartphone",
  aspect_ratio: "portrait",
  quality: "hd",
  output_directory: "./product_images",
  filename: "smartphone_hero",
  output_format: "png",
  include_base64: true,
});

Image Editing

// Generate base image
const baseImage = await client.callTool("generate-image", {
  prompt: "A mountain landscape",
  aspect_ratio: "landscape",
});

// Edit the generated image
const editedImage = await client.callTool("edit-image", {
  source_image: {
    type: "local",
    value: baseImage.data.file_path,
  },
  edit_prompt: "Add dramatic storm clouds",
  edit_type: "background_change",
  strength: 0.7,
});

Batch Processing

// Process multiple images
const result = await client.callTool("batch-edit", {
  images: [
    { type: "local", value: "image1.jpg" },
    { type: "local", value: "image2.jpg" },
    { type: "local", value: "image3.jpg" },
  ],
  edit_prompt: "Apply Instagram-style filter",
  edit_type: "style_transfer",
  batch_settings: {
    max_concurrent: 3,
    error_handling: "continue_on_error",
  },
});

Development

Contributing

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

Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run linting
npm run lint

# Type checking
npm run typecheck

Building

# Build for production
npm run build

# Development mode with hot reload
npm run dev

License

MIT License - see the LICENSE file for details.

Support

• Documentation - Full documentation and examples
• GitHub Issues
• OpenAI API Documentation
• MCP Protocol Documentation