OpenAI GPT Image

by SureScaleAI

104 stars

603 downloads

Not rated

GitHub

About

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

Details

Author: SureScaleAI
GitHub stars: 104
Downloads: 603
Categories: Developer Tools, AI, Other

- Generate images from text prompts with size, quality, and background options.
- Edit images using inpainting, outpainting, or compositing with a mask.
- Supports file paths and base64 input for source images and masks.
- Automatic file output when total image size exceeds the 1MB MCP payload limit.
- Works with OpenAI and Azure OpenAI deployments.
- Configurable working directory via the MCP_HF_WORK_DIR environment variable.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name OpenAI GPT Image

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

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

JSON

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

JSON

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

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

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

JSON

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

JSON

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

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

From the repository

Clone the repository, install dependencies with yarn install, and build with yarn build. Then add a configuration entry to your MCP client (e.g., Claude Desktop or VSCode) specifying the path to dist/index.js and your OpenAI API key (or Azure credentials). The server exposes two tools: create-image (generate images) and edit-image (edit images with optional mask). Image output can be saved to disk or returned as base64.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

McpServers

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

openai-gpt-image-mcp

<p align="center">
<a href="https://www.npmjs.com/package/@modelcontextprotocol/sdk"> MCP SDK </a>
<a href="https://www.npmjs.com/package/openai"> OpenAI SDK </a>
<a href="https://github.com/SureScaleAI/openai-gpt-image-mcp/blob/main/LICENSE"> License </a>
<a href="https://github.com/SureScaleAI/openai-gpt-image-mcp/stargazers"></a>
<a href="https://github.com/SureScaleAI/openai-gpt-image-mcp/actions"></a>
</p>

---

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 limit if returned as base64.
- Auto-Switch to File Output: If the total image size exceeds 1MB, the tool will automatically save images to disk and return the file path(s) instead of base64. This ensures compatibility and prevents errors like result exceeds maximum length of 1048576.
- Default File Location: If you do not specify a file_output path, images will be saved to /tmp (or the directory set by the MCP_HF_WORK_DIR environment variable) with a unique filename.
- Environment Variable:
- MCP_HF_WORK_DIR: Set this to control where large images and file outputs are saved. Example: export MCP_HF_WORK_DIR=/your/desired/dir
- Best Practice: For large or production images, always use file output and ensure your client is configured to handle file paths.

---

📚 References

- OpenAI Images API Documentation

---

🙏 Credits

- Built with @modelcontextprotocol/sdk
- Uses openai Node.js SDK
- Built by SureScale.ai
- Contributions from Axle Research and Technology

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

openai-gpt-image-mcp

✨ Features

🚀 Installation

🔑 Configuration

⚡ Advanced

🧑‍💻 Development

📝 License

🩺 Troubleshooting

⚠️ Limitations & Large File Handling

📚 References

🙏 Credits

Install

More like this

Sequential Thinking

Sentry

Github

Filesystem

EverArt

Google Drive