OpenAI Image Server

MCP server for OpenAI gpt-image models — generate, edit, and multi-turn edit images straight from Claude (or any MCP client).

Tools

• generate_image — text → image(s)
• edit_image — edit / extend / compose with an optional mask
• edit_image_conversation — multi-turn iterative edit (Responses API)
• image_capabilities — discover models, params, pricing as-of date

---

Quick start

1. Get the code & build

git clone <repo-url> openai-image-mcp
cd openai-image-mcp
npm install
npm run build

npm run build produces dist/index.js — the entrypoint you point Claude at.

2. Register with Claude Code (one command)

claude mcp add openai-image --scope user \
  --env OPENAI_API_KEY=sk-your-openai-api-key \
  --env IMAGE_OUTPUT_DIR=/absolute/path/to/images \
  -- node /absolute/path/to/openai-image-mcp/dist/index.js

• Use an absolute path to dist/index.js (output of step 1).
• IMAGE_OUTPUT_DIR is where generated images are written. Optional — defaults to ~/Pictures/openai-image-mcp.
• --scope user makes it available in every project. Use --scope project to limit it to the current repo.

Verify it registered:

claude mcp list

3. Use it

In Claude, just ask — e.g. "generate an image of a red bicycle on the beach". The server writes the file under IMAGE_OUTPUT_DIR and returns the path.

---

Configuration (env vars)

Var	Required	Default	Purpose
OPENAI_API_KEY	yes¹	—	OpenAI API key
OPENAI_API_KEY_FILE	yes¹	—	path to a file containing the API key (trailing whitespace trimmed); used when OPENAI_API_KEY is unset
IMAGE_OUTPUT_DIR	no	~/Pictures/openai-image-mcp	where images are saved
DEFAULT_MODEL	no	gpt-image-2	gpt-image-1 / gpt-image-1-mini / gpt-image-2
DEFAULT_OUTPUT_MODE	no	path	path | base64 | both
MAX_COST_PER_CALL_USD	no	—	reject a call whose estimate exceeds this
CONFIRM_ABOVE_N	no	—	require confirm:true when generating more than N images
ALLOW_URL_INPUT	no	false	allow image inputs given as URLs (see Security)

¹ Exactly one of OPENAI_API_KEY or OPENAI_API_KEY_FILE is required. Prefer OPENAI_API_KEY_FILE pointing to a chmod 600 file so the key does not live in client config files. | SPEND_LOG_PATH | no | — | append per-call cost records as JSONL | | PROMPT_ENHANCE | no | false | locally augment short prompts (no extra LLM call) | | OPENAI_BASE_URL | no | — | override API base URL | | LOG_LEVEL | no | info | debug | info | warn | error |

Add any of these as extra --env KEY=value flags on the claude mcp add command.

---

Manual MCP config (other clients)

If your client uses a JSON config (Claude Desktop, Cursor, VSCode), add:

{
  "mcpServers": {
    "openai-image": {
      "command": "node",
      "args": ["/absolute/path/to/openai-image-mcp/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-your-openai-api-key",
        "IMAGE_OUTPUT_DIR": "/absolute/path/to/images"
      }
    }
  }
}

---

Security notes

• URL image input is off by default. Set ALLOW_URL_INPUT=true to enable. When on, fetches resolve all DNS addresses and reject any private / loopback / link-local / CGNAT / IPv4-mapped target, re-validating on every redirect hop (SSRF guard).
• Output paths are confined to IMAGE_OUTPUT_DIR; existing files are never overwritten (a numeric suffix is added on collision).
• Logs go to stderr only; stdout is reserved for the MCP protocol.

---

Development

npm test          # run the vitest suite
npm run typecheck # tsc --noEmit
npm run build     # compile to dist/

Notes

• Models: gpt-image-1 (deprecating 2026-10-23), gpt-image-1-mini, gpt-image-2 (default).
• DALL-E was removed from the OpenAI API (2026-05-12) — not supported.
• Pricing data is as of 2026-06; query the image_capabilities tool for details.