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 2 wired — the live OpenAI call (src/openaiImageClient.ts) is implemented with typed 429/timeout/5xx mapping, and every upstream branch is mock-reproduced in tests. The default provider is still mock; a real paid API call happens only when you explicitly set IMAGE_MCP_PROVIDER=openai with an OPENAI_API_KEY. Real-API E2E evidence is still pending. 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 schema-validated structuredContent with { provider, model, size, quality, requested_output_format, output_format, request_id }. requested_output_format records the request; output_format describes the bytes actually returned and always agrees with mimeType.

Related MCP server: gemini-nano-banana-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.

Experimental: pluggable provider lane (detachable)

Besides mock and openai, the server can load an external provider plugin (e.g. a Codex-CLI-backed lane that generates images inside a ChatGPT subscription instead of API billing). The core stays API-key-first; the plugin lane is strictly opt-in and detachable by design:

• Activation needs both IMAGE_MCP_PROVIDER=plugin and IMAGE_MCP_PROVIDER_MODULE=<npm package or path>. Remove both to detach — the core has no build-time dependency on any plugin.

• A plugin implements the contract exported at claude-openai-image-mcp/provider (createImageProvider() + providerApiVersion). The server refuses to start on a version mismatch or any load failure (fail-closed).

• Every provider (plugin or not) runs behind a request-time guard: timeout with abort, strict base64 + magic-byte/MIME validation, decoded-size cap, and redacted error surfacing. A plugin cannot impersonate another lane in structuredContent.

• There is no automatic fallback between lanes. If the plugin lane breaks (e.g. an upstream policy change), requests fail with a clear error; switching back to openai is a deliberate env change, never implicit billing.

• Trust model: the plugin runs in-process with the server's full privileges. Only install plugins you wrote or audited, and do not keep OPENAI_API_KEY in the plugin lane's environment (the server warns if you do). A plugin backend may choose its own model; results report what the plugin actually used (or unknown) — the configured model is advisory there.

A reference implementation lives in packages/codex-plugin-cc — the ChatGPT-subscription lane (drives the Codex CLI, no API key). It is a separate, non-core package: the core never imports it, and a dedicated CI job builds, audits, and tests it separately so it stays detachable from the core dependency graph.

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. ✅ — implemented; real API E2E still requires explicit approval (billing) and is the remaining checkbox of this phase.

• 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 — the core stays server-side API key only. Unofficial subscription-backed lanes live as external plugins (see the pluggable provider lane above), at the user's own risk.

License

MIT