GPT Image

A Model Context Protocol (MCP) server for generating and editing images using the OpenAI gpt-image-1 model.

javascript

18

GitHub Stars

javascript

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "cloudwerx-dev-gpt-image-1-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@cloudwerxlab/gpt-image-1-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "PASTE_YOUR_OPENAI_API_KEY_HERE",
        "GPT_IMAGE_OUTPUT_DIR": "OPTIONAL: PATH_TO_SAVE_GENERATED_IMAGES"
      }
    }
  }
}

You run a focused MCP server that uses the OpenAI gpt-image-1 model to generate and edit images. It saves outputs to disk, supports configurable output paths, and provides structured results with helpful metadata for each request.

How to use

You use this MCP server by connecting an MCP client. Start the local server with the provided command, set your API key, and optionally customize where generated images are saved. Then issue tool calls to create_image for generation or create_image_edit for edits, and read back the resulting image files and metadata.

Practical usage patterns you can perform:

Generate a new image from a text prompt by calling create_image with a prompt and optional size and quality settings.
Edit an existing image by calling create_image_edit with the image (as a file path or base64 data), a prompt describing the edit, and an optional mask to constrain edits.
Review the server’s response for file paths to the generated images, token usage details, and error information when something goes wrong.

How to install

Prerequisites you must meet before starting:

Node.js 14 or higher
An OpenAI API key with access to the gpt-image-1 model

Step 1: Set up your environment variables

OPENAI_API_KEY: Your OpenAI API key
GPT_IMAGE_OUTPUT_DIR: Optional path to save generated images (defaults to a gpt-image-1 folder under your Pictures directory if not set)

Step 2: Start the MCP server using NPX without installing locally (quick start)
- Ensure you have Node.js installed
- Run: `npx -y @cloudwerxlab/gpt-image-1-mcp

Additional content

Environment variables drive where outputs are stored and how authentication is handled. The server saves generated images to disk automatically, using either the default Pictures-based path or a custom directory you specify via GPT_IMAGE_OUTPUT_DIR. It also reports token usage and provides detailed error information to help you troubleshoot.

Integration notes include how to configure an MCP client with a local stdio server. The recommended local runtime is to run the server with npx -y @cloudwerxlab/gpt-image-1-mcp, supplying the required environment variables above.

Troubleshooting highlights you may encounter include MIME type errors when handling image-like data, API key authentication issues, build errors if you clone and build from source, and output directory permission problems. Ensure file extensions match the actual image formats, verify your API key, install dependencies if building from source, and confirm write permissions to the configured output directory.

Available tools

create_image

Generate a new image from a text prompt with options for size, quality, and output format.

create_image_edit

Edit an existing image using a text prompt and optional mask to constrain edits, with support for file path or base64 image data.