openai-gpt-image-mcp

A Model Context Protocol (MCP) tool server for OpenAI's GPT-4o/gpt-image-1 image generation and editing APIs.

• Generate images from text prompts using OpenAI's latest models.
• Edit images (inpainting, outpainting, compositing) with advanced prompt control.
• Supports: Claude Desktop, Cursor, VSCode, Windsurf, and any MCP-compatible client.

✨ Features

• create-image: Generate images from a prompt, with advanced options (size, quality, background, etc).
• edit-image: Edit or extend images using a prompt and optional mask, supporting both file paths and base64 input.
• File output: Save generated images directly to disk, or receive as base64.

🚀 Installation

git clone https://github.com/SureScaleAI/openai-gpt-image-mcp.git
cd openai-gpt-image-mcp
yarn install
yarn build

🔑 Configuration

Add to Claude Desktop or VSCode (including Cursor/Windsurf) config:

{
  "mcpServers": {
    "openai-gpt-image-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

Also supports Azure deployments:

{
  "mcpServers": {
    "openai-gpt-image-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": { 
        "AZURE_OPENAI_API_KEY": "sk-...",
        "AZURE_OPENAI_ENDPOINT": "my.endpoint.com",
        "OPENAI_API_VERSION": "2024-12-01-preview"
      }
    }
  }
}

Also supports supplying an environment files:

{
  "mcpServers": {
    "openai-gpt-image-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js", "--env-file", "./deployment/.env"]
    }
  }
}

⚡ Advanced

• For create-image, set n to generate up to 10 images at once.
• For edit-image, provide a mask image (file path or base64) to control where edits are applied.
• Provide an environment file with --env-file path/to/file/.env
• See src/index.ts for all options.

🧑‍💻 Development

• TypeScript source: src/index.ts
• Build: yarn build
• Run: node dist/index.js

📝 License

MIT

🩺 Troubleshooting

• Make sure your OPENAI_API_KEY is valid and has image API access.
• You must have a verified OpenAI organization. After verifying, it can take 15–20 minutes for image API access to activate.
• File paths must be absolute.
  • Unix/macOS/Linux: Starting with / (e.g., /path/to/image.png)
  • Windows: Drive letter followed by : (e.g., C:/path/to/image.png or C:\path\to\image.png)
• For file output, ensure the directory is writable.
• If you see errors about file types, check your image file extensions and formats.

⚠️ Limitations & Large File Handling

• 1MB Payload Limit: MCP clients (including Claude Desktop) have a hard 1MB limit for tool responses. Large images (especially high-res or multiple images) can easily exceed this li

... View full README on GitHub