mcp-gpt-image

Português

MCP server and skill that let Claude Code generate and edit images with GPT Image through your local Codex CLI. Uses your ChatGPT login. No OpenAI API key.

Claude writes the prompt. Codex passes it to its built-in image_gen tool. The image is saved to disk and returned to Claude inline. The skill makes Claude ask a short round of questions first (at most 4, only what changes the image), then review every image against a strict checklist and regenerate (up to 3 attempts) until it passes.

Requirements

• Node.js 20 or newer

• git (npx downloads this package from GitHub)

• Claude Code

• Codex CLI, signed in with a ChatGPT plan that includes image generation:

npm install -g @openai/codex

codex login

Related MCP server: GPT Image 2 MCP Server

Install

npx -y github:Monayzera/mcp-gpt-image setup

This does three things:

1. Copies the skill (SKILL.md and styles.md) to ~/.claude/skills/gpt-image/ (or $CLAUDE_CONFIG_DIR/skills/gpt-image/).

2. Registers the MCP server in Claude Code at user scope, as npx -y github:Monayzera/mcp-gpt-image (on Windows, wrapped in cmd /c). If CODEX_PATH is set, it is passed to the server. An existing gpt-image entry at user scope is left unchanged; one in another scope is reported so you can remove it.

3. Checks that Codex is installed and signed in.

Restart Claude Code afterwards. claude mcp list should show gpt-image as connected.

Running setup again replaces the skill file with the latest version, including any local edits. npx fetches the newest commit on each start, so the server updates by itself.

To register only the MCP server, without the skill:

claude mcp add --scope user gpt-image -- npx -y github:Monayzera/mcp-gpt-image

Uninstall

npx -y github:Monayzera/mcp-gpt-image uninstall

Removes the skill and runs claude mcp remove gpt-image --scope user.

Use

Ask Claude for an image. The skill takes over: questions, prompt, generation, review, retries.

Questions come in one round of at most 4, each with a recommended option first. Claude skips anything your request already answers, and skips the round entirely when the request is complete or you say "no questions" / "sem perguntas".

Make a 16:9 hero image for the landing page: a matte black coffee grinder on a concrete counter, soft window light.

Edit assets/logo.png: keep the shape, make the background transparent.

To use a real logo, product or photo, paste or attach the image in the chat. Claude Code gives Claude its file path, and Claude passes it in reference_images.

styles.md holds prompt recipes for photo and illustration styles (phone snapshot, editorial, film, product, documentary, cinematic, flat vector, 3D, watercolor, comic, logo, poster, and more). Each one is tagged with how it was verified: tested here, OpenAI documentation, or community sources.

Size and aspect ratio are not parameters. They go in the prompt: "16:9" returned 1672x941 in testing.

Tools

generate_image

The result lists each saved path with its size, the prompt that reached GPT Image (when Codex reports it), the alpha check when transparency was requested, and the usage limits Codex reports (5-hour and weekly windows).

get_image_result

Returns the result of a background: true job: the same text and images as a normal call, or its status while it runs. wait_seconds (0-600) waits at most that long and returns as soon as the job finishes. Images are returned on the first successful collection only. At most 4 jobs run at once; finished jobs are kept for 1 hour and are lost if the server restarts.

Claude Code can also move any long MCP call to the background by itself. To make that happen after 10 seconds instead of 2 minutes, add "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "10000" to the env block of ~/.claude/settings.json. In the Claude desktop app (Code tab) also add "CLAUDE_AUTO_BACKGROUND_TASKS": "1"; without it the call was not moved to the background in testing.

codex_status

Shows the Codex path and version, sign-in state, usage limits with reset times, the Codex config default model, the models with the reasoning efforts each one accepts, and the save folder.

Prompt modes

In exact mode Codex is told to call image_gen with your text, character for character. The prompt that reached GPT Image is compared with yours, and the result says whether they match.

The Codex model and reasoning effort do not draw the image. The model matters most in enhance mode, where it writes the final prompt.

Files

• <project>: CLAUDE_PROJECT_DIR if set, else the workspace root reported by Claude Code, else the current directory.

• Default name: date, time and the first six words of the prompt, e.g. generated-images/2026-10-14_120030_a-minimalist-flat-illustration-of-a.png.

• Several images get _1, _2, ...

• Existing files are never overwritten. A -2, -3, ... suffix is added.

• Codex also keeps its own copy in ~/.codex/generated_images/.

Settings

The automatic search checks PATH, then common install folders: the official installer folder (~/.local/bin, or %LOCALAPPDATA%\Programs\OpenAI\Codex\bin on Windows), npm global, nvm, pnpm, Volta, Bun, asdf and Homebrew.

claude mcp add --scope user gpt-image -e GPT_IMAGE_MODEL=gpt-6-astra -e GPT_IMAGE_EFFORT=max -- npx -y github:Monayzera/mcp-gpt-image

setup passes CODEX_PATH, GPT_IMAGE_MODEL and GPT_IMAGE_EFFORT to the server when they are set in your shell.

In exact mode the Codex model only relays the prompt. In testing, the same prompt with gpt-6-astra and effort max used about 4% of the 5-hour window, against about 1% with the default model and effort low, and the image was not better.

Troubleshooting

How it works

1. On the first call the server starts codex app-server (JSON-RPC over stdio) and keeps it running.

2. Each request opens an ephemeral, read-only Codex thread whose instructions are to call image_gen with the prompt.

3. Codex reports each imageGeneration item. The server writes each image to disk and returns it with the usage limits Codex reports.

License

MIT