openai-imagegen-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| IMAGEGEN_HOME | No | Folder that holds saved images. Must be an absolute path or start with ~/. | ~/.openai-imagegen-mcp |
| IMAGEGEN_MAX_N | No | Most images allowed in one call, from 1 to 10. | 4 |
| OPENAI_API_KEY | Yes | API key sent to the endpoint. | |
| OPENAI_BASE_URL | No | API root. /v1 is added if the URL has no path. | https://api.openai.com/v1 |
| IMAGEGEN_WAIT_SECONDS | No | How long one tool call waits before returning a job. Must be shorter than your client's tool timeout. | 50 |
| IMAGEGEN_REQUEST_TIMEOUT_SECONDS | No | Timeout for each request to the API. | 300 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Images are saved to local files. A result carries a downscaled preview for you to inspect and the path of the full-size original. If a tool returns status "running", the image is still being made: call get_image_result with the job_id. Do not start the request again, because that would create and bill a new image.
Saving: always pass your current working directory as workspace, which groups images by project. Omit it if you do not know the directory. When showing an image to the user, always use the original file at its path, never the preview, and tell the user the full path. If your environment gives you a session scratchpad folder and your file-sharing tool only displays images from certain folders, copy the original there before sharing it, without downscaling it. Still report the original path, because the scratchpad is temporary. If the user named a destination or the image is for the current project, copy it there and keep the original. Do not overwrite existing files; use a new name such as hero-v2.png instead.
Writing prompts: always write the prompt in English, translating the request if needed. Keep text that should appear in the image in its original language. State the subject and intended use, then composition, style, lighting and materials. For complex requests, use labeled sections for scene, subject, details and constraints. Put required text in quotes, say where it goes and how many times it appears, and ask for no extra text. For edits, say what to change and list what must stay unchanged. With several input images, refer to each by number and give its role. Refine by passing the previous output as the next input and changing one thing at a time. Check text, labels and numbers in the result, because the model can get them wrong.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| generate_imageA | Generate images from a text prompt and save them to local files. Returns downscaled previews and the paths of the originals. Supports raster output and animated GIF. If the result has status "running", call get_image_result with its job_id. |
| edit_imageA | Edit local images, or create a new image from local reference images, and save the result to local files. Returns downscaled previews and the paths of the originals. The first image is the one edited; the others serve as references. If the result has status "running", call get_image_result with its job_id. |
| get_image_resultA | Wait for and return the result of a job that generate_image or edit_image reported as "running". Waits for a limited time; if the result still has status "running", call this tool again. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 3 tools
Each tool maps to a distinct action: creating new images, editing/conditioning on existing images, and polling an async job. The descriptions explicitly cross-reference each other (generate/edit tell you to call get_image_result when status is "running"), leaving no ambiguity about selection.
All three names are snake_case verb_noun(ish) forms: generate_image, edit_image, get_image_result. The only slight deviation is the longer 'get_image_result' suffix pattern, but it still follows the convention predictably.
Three tools is at the low end of the ideal range, but each is clearly necessary for the domain: creation, editing, and async result retrieval. Nothing feels redundant or bloated.
The core lifecycle (generate, edit, poll async result) is covered with no dead ends, since the async pattern is explicitly handled. Minor gaps exist: no job listing/cancellation and no metadata or parameter-enumeration tool, though these are workable around.