codex-gpt-image-mcp

<div align="center"> <h1>Codex GPT Image MCP</h1> <p>Use your own OpenAI-compatible image API from Codex with local files and inline previews.</p> <p> <a href="#english">English</a> </p> <p> <img src="https://img.shields.io/badge/MCP-stdio-111827" alt="MCP stdio" /> <img src="https://img.shields.io/badge/Codex-plugin-111827" alt="Codex plugin" /> <img src="https://img.shields.io/badge/Model-gpt--image--2-18A978" alt="gpt-image-2" /> <img src="https://img.shields.io/badge/License-MIT-1769E0" alt="MIT License" /> </p> </div>  ## Tool List ### The problem When Codex Desktop is authenticated with an API key, its built-in image-generation tool may be unavailable even though the configured provider supports `gpt-image-2`. Codex then has no native way to call that API, save originals, edit local images, and render a result inline. This project exposes an OpenAI-compatible image service as a local stdio MCP server and includes Codex plugin metadata plus a reusable skill. It provides three tools: - `image_service_status`: reports configuration without returning the API key. - `generate_image`: generates images, saves originals, and returns compact inline previews. - `edit_image`: edits local images with multiple references and an optional mask. It supports the Images API, the Responses API `image_generation` tool, and an `auto` mode that falls back to Responses after `404`, `405`, or `501`. The fallback uses the same configured provider; it never silently changes providers. ### Requirements - Codex CLI or Codex Desktop - Node.js 20+ - An OpenAI-compatible API supporting Images or Responses image generation ### Quick start ```powershell git clone https://github.com/Xuan-BOMS/codex-gpt-image-mcp.git "$HOME\plugins\gpt-image-mcp" Set-Location "$HOME\plugins\gpt-image-mcp\server" npm ci --omit=dev ``` Configure Windows user environment variables with hidden key input: ```powershell powershell -ExecutionPolicy Bypass -File "$HOME\plugins\gpt-image-mcp\scripts\configure.ps1" ` -BaseUrl "https://api.openai.com/v1" ` -Model "gpt-image-2" ` -ApiMode "auto" ``` Add the following to `~/.codex/config.toml`, replacing the server path with an absolute local path: ```toml [mcp_servers.gpt-image] command = "node" args = ["C:\\Users\\YOUR_NAME\\plugins\\gpt-image-mcp\\server\\index.mjs"] env_vars = [ "GPT_IMAGE_API_KEY", "GPT_IMAGE_BASE_URL", "GPT_IMAGE_MODEL", "GPT_IMAGE_RESPONSES_MODEL", "GPT_IMAGE_API_MODE", "GPT_IMAGE_USER_AGENT", "GPT_IMAGE_OUTPUT_DIR", "GPT_IMAGE_ALLOWED_ROOTS", "GPT_IMAGE_TIMEOUT_MS", "OPENAI_API_KEY", "OPENAI_API_BASE_URL" ] startup_timeout_sec = 20 tool_timeout_sec = 1200 ``` Run `codex mcp list --json`, fully exit Codex including its tray process, restart it, and open a new task. ### Features - Supports `gpt-image-2` generation and editing. - Returns local absolute paths, `file://` URIs, usage, and up to 4 inline previews. - Supports PNG, JPEG, WebP, sizes, quality, backgrounds, moderation levels, and compression ratios. - Supports up to 10 results for the same prompt, 16 input reference images, and PNG masks. - Default 20-minute timeout, suitable for slower image models. - API keys read only from environment variables, not appearing in tool arguments, prompts, or error messages. - Input/output paths restricted to the user's home directory by default; extensible via allowed directory configuration. - Includes fully local protocol testing without consuming real API quotas. ### Environment Variables | Variable | Default Value | Description | | --- | --- | --- | | `GPT_IMAGE_API_KEY` | None | Required. Also compatible with `OPENAI_API_KEY`. | | `GPT_IMAGE_BASE_URL` | OpenAI SDK default | API root URL. Also compatible with `OPENAI_API_BASE_URL`. | | `GPT_IMAGE_MODEL` | `gpt-image-2` | Image model. | | `GPT_IMAGE_RESPONSES_MODEL` | `gpt-5.6` | Responses backend main model for calling image tools. | | `GPT_IMAGE_API_MODE` | `auto` | `auto`, `images`, or `responses`. | | `GPT_IMAGE_OUTPUT_DIR` | `~/.codex/generated_images/gpt-image-mcp` | Original image output directory. | | `GPT_IMAGE_ALLOWED_ROOTS` | User's home directory | Additional allowed paths; Windows uses `;`, macOS/Linux use `:`. | | `GPT_IMAGE_TIMEOUT_MS` | `1200000` | API timeout in milliseconds. | | `GPT_IMAGE_USER_AGENT` | OpenAI SDK default | For certain compatible gateways that filter by client identifier. | When using the Responses backend, main model tokens and image generation may be billed separately; check your provider's billing details. ### Tool Examples ```text Call image_service_status. ``` ```text Use generate_image to generate a 1536x1024, medium-quality cinematic cityscape at night, returning an inline preview. ``` ```text Use edit_image to edit C:\path\photo.png, replacing only the sky while keeping other content unchanged. ``` ### Testing ```powershell Set-Location server npm ci npm test npm audit --omit=dev ``` Tests launch a temporary local API covering Images, Responses, and automatic fallback paths without accessing real image services. ### Frequently Asked Questions **The skill appeared but the tool did not.** The skill file and MCP tool are two independent loading paths. Run `codex mcp list --json` to confirm `gpt-image` exists and is enabled; then fully exit Codex including its tray process, restart it, and open a new task. Old tasks cannot hot-load new MCP tools. **Images API returns 404.** Use `GPT_IMAGE_API_MODE=auto`. The service attempts Responses `image_generation`, provided the gateway supports this tool. **Compatible gateway returns 403, but Codex text requests are fine.** Some gateways filter by `User-Agent`. Set `GPT_IMAGE_USER_AGENT` only if you trust the gateway; do not put authentication information in this variable. **Requested 1024x1024 but received a different size.** The service passes size parameters to the upstream but compatible vendors may ignore them. Returned files retain the original size; they are not silently scaled. ### Security Design - No API key field in MCP tool parameters. - Error messages sanitize API keys and Bearer tokens. - Only allows reading images within the user's home directory by default. - Output files use non-overwriting writes; generates an alternate filename if the name already exists. - Inline previews compress to a maximum 512px JPEG; originals are saved locally. ### Relationship with gpt-image-2-webui This project was inspired by [JunWan666/gpt-image-2-webui](https://github.com/JunWan666/gpt-image-2-webui)'s OpenAI-compatible interface, long timeouts, local saving, and image editing workflow. The two projects serve different use cases: `gpt-image-2-webui` offers a complete browser-based workspace, while this project is an independently implemented stdio MCP server enabling Codex to directly call image capabilities in conversations. This repository did not copy its source code. ### Prompt-based Installation Set `GPT_IMAGE_API_KEY` and `GPT_IMAGE_BASE_URL` first. Then paste this prompt into a Codex task with terminal and file-editing access. Never paste the actual key into the prompt. ```text Install and configure https://github.com/Xuan-BOMS/codex-gpt-image-mcp. Execute the work instead of only giving me commands. Requirements: 1. Clone or update the repository at ~/plugins/gpt-image-mcp. 2. Run npm ci --omit=dev in server. 3. Preserve all existing ~/.codex/config.toml content. Only add or update mcp_servers.gpt-image, use the absolute path to server/index.mjs, and forward every GPT_IMAGE_* variable through env_vars. 4. Do not read, print, copy, or persist my API key. It is already available in the user environment. 5. Run npm test and codex mcp list --json; verify that gpt-image is enabled. 6. Tell me to fully exit Codex and open a new task. Do not change unrelated MCP servers, plugins, or AGENTS.md. The repository root is also a Codex plugin. An installer agent can clone it to `~/plugins/gpt-image-mcp`, add it to the personal marketplace, install `gpt-image-mcp@personal`, and verify it with `codex mcp list --json`. ``` ### Configuration | Variable | Default | Purpose | | --- | --- | --- | | `GPT_IMAGE_API_KEY` | none | Required; `OPENAI_API_KEY` is also accepted. | | `GPT_IMAGE_BASE_URL` | OpenAI SDK default | Provider root; `OPENAI_API_BASE_URL` is also accepted. | | `GPT_IMAGE_MODEL` | `gpt-image-2` | Image model. | | `GPT_IMAGE_RESPONSES_MODEL` | `gpt-5.6` | Mainline model used by the Responses backend. | | `GPT_IMAGE_API_MODE` | `auto` | `auto`, `images`, or `responses`. | | `GPT_IMAGE_OUTPUT_DIR` | `~/.codex/generated_images/gpt-image-mcp` | Original output directory. | | `GPT_IMAGE_ALLOWED_ROOTS` | home directory | Extra roots separated by the platform path delimiter. | | `GPT_IMAGE_TIMEOUT_MS` | `1200000` | Upstream timeout in milliseconds. | | `GPT_IMAGE_USER_AGENT` | SDK default | Optional compatibility override for restrictive gateways. | Responses mode can incur both mainline-model token usage and image-generation charges. Refer to your provider's billing. ### Verification ```powershell Set-Location server npm ci npm test npm audit --omit=dev ``` The protocol test uses a temporary local mock API. It covers Images, Responses, inline previews, local files, edits, and automatic fallback without spending API credits. ### Troubleshooting - **The skill is visible but tools are missing:** skills and MCP tools load independently. Check `codex mcp list --json`, fully quit Codex, restart, and create a new task. Existing tasks cannot hot-load MCP tools. - **Images endpoints return 404:** use `GPT_IMAGE_API_MODE=auto` and confirm the gateway supports Responses image generation. - **The requested dimensions are not respected:** compatible providers may ignore size. This server preserves the upstream original instead of resizing silently. - **A gateway blocks the SDK client:** set `GPT_IMAGE_USER_AGENT` only when required by a trusted gateway. ### Credits Inspired by the OpenAI-compatible configuration, long-running image requests, local output, and editing workflow in [JunWan666/gpt-image-2-webui](https://github.com/JunWan666/gpt-image-2-webui). That project is a browser workbench; this repository is an independent MCP implementation for direct Codex tool calls. No source code was copied. ## License MIT