claude-openai-image-mcp

A small, security-first MCP server that generates images with OpenAI's image model (gpt-image-2) and returns them as MCP image content — usable from Claude Code (CLI), Claude Desktop, and other stdio MCP clients.

The OpenAI API key is held server-side only. The default provider is a mock that returns a real 1×1 PNG with no network call and no billing, so you can wire up and test the whole flow before spending a cent.

Status: Phase 1 — repo scaffold, generate_image tool, mock provider, CI. The live OpenAI call is a documented skeleton (src/openaiImageClient.ts) that fails closed until Phase 2. See Roadmap.

Tool

generate_image

The server chooses the model; clients never pass a model name. Requests outside the allowlist are rejected before any provider call.

Returns MCP image content { type: "image", data: <base64>, mimeType } plus structuredContent with { provider, model, size, quality, output_format, request_id }.

Related MCP server: io.github.pvliesdonk/image-generation-mcp

Quick start

Requires Node ≥ 22.12 and pnpm.

pnpm install
cp .env.example .env        # defaults to the mock provider (no key needed)
pnpm run build
pnpm test

Run the server over stdio:

pnpm run dev                # tsx src/index.ts
# or, after build:
node dist/index.js

Register with Claude Code

claude mcp add openai-image -- node /absolute/path/to/dist/index.js

(For the mock provider no OPENAI_API_KEY is needed. To use the real API later, set IMAGE_MCP_PROVIDER=openai and OPENAI_API_KEY in the server's environment.)

Configuration

All configuration is via environment variables (see .env.example). .env is git-ignored — never commit real secrets.

Provisional values

quality=low, concurrency=1, retries=0, n=1, and model=gpt-image-2 are provisional — chosen to bound cost and latency and to be confirmed by end-to-end evidence. Each carries a review condition in code comments; expect them to change as we run real E2E tests.

Security

The OpenAI key is server-side only and never logged, serialized, or returned. Logs are stderr-only, metadata-only, and redacted. See SECURITY.md.

Development

pnpm run lint:ox        # fast Rust correctness pass
pnpm run format:check   # prettier
pnpm run lint           # eslint
pnpm run typecheck      # tsc --noEmit
pnpm run build
pnpm test               # vitest (no network, no billing)

CI runs the same sequence (.github/workflows/node.js.yml) plus CodeQL.

Roadmap

• Phase 1 (this repo): scaffold, generate_image, mock provider, CI. ✅

• Phase 2: wire OpenAIImageProvider to the official SDK (allowlist, timeout, bounded retry, 429/Retry-After/timeout/5xx mapping, byte/MIME checks); mock-reproduce every branch. Real API E2E only after explicit approval.

• Phase 3: Streamable HTTP transport + client→server OAuth (the OpenAI key is never forwarded to clients). Note: there is no official OpenAI OAuth path to call the Images API on a ChatGPT user's behalf — server-side API key only.

License

MIT