gpt-image-1 MCP

MCP server for AI-powered image generation using OpenAI's gpt-image-1 model 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-1-mcp": {
      "command": "npx",
      "args": ["@napolab/gpt-image-1-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-your-api-key"
      }
    }
  }
}

Alternative: Local Installation

npm install -g @napolab/gpt-image-1-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-1-mcp": {
      "command": "npx",
      "args": ["@napolab/gpt-image-1-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-your-api-key"
      }
    }
  }
}

Configuration

Environment Variables

Available Tools

generate-image

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

Parameters:

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:

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:

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