Skip to main content
Glama

image-gen MCP

An MCP server that lets Claude generate images on demand using a ChatGPT plan through Codex CLI, with a free FLUX fallback. It works locally over stdio and can also be hosted over HTTPS as a Claude custom connector.

  • Primary backend: Codex CLI $imagegen (uses the signed-in ChatGPT/Codex quota, no API key)

  • Fallback: Pollinations FLUX (free, keyless)

  • Tools: generate_image, get_image_job, image_backend_status

  • Zero npm dependencies

Not affiliated with OpenAI, Anthropic, or Tailscale. Use your own account and follow each service's terms.

Requirements

  • Windows 10/11 (the helper scripts are PowerShell; the server itself is Node.js)

  • Node.js 18 or newer

  • A ChatGPT plan that includes Codex image generation

  • Optional for remote hosting: Tailscale (preferred) or Cloudflare Tunnel

Related MCP server: codex-image

Quick start (local stdio)

npm install -g @openai/codex
codex login

Verify:

codex login status

Clone the repo and register the server with Claude Code:

git clone https://github.com/barnikbhai2007/image-gen-mcp.git
cd image-gen-mcp
node install.mjs

install.mjs writes an image-gen entry to %USERPROFILE%\.claude.json at user scope. Re-run it any time; it backs up the file first and only replaces the image-gen entry.

Start a new Claude Code session and ask:

Generate an image of a cozy bookstore on a rainy evening

Images are saved to %USERPROFILE%\Pictures\Claude Images by default.

Host it as a custom connector

Claude Desktop's Add custom connector dialog needs a public HTTPS MCP URL. This repo can serve Streamable HTTP and publish it through a tunnel.

  1. Install Tailscale and sign in.

  2. Enable Funnel for your tailnet when Tailscale asks (or in the admin console).

  3. Run:

.\start-host.ps1

The script starts the HTTP server, enables Funnel on port 8788, and prints a URL like:

https://your-machine.your-tailnet.ts.net/mcp/<secret>

The hostname stays the same across restarts. The /mcp/<secret> path is generated once and stored in http-secret.txt, so the full connector URL does not change.

Check the Funnel directly:

tailscale funnel status

Option B: Cloudflare quick tunnel (temporary URL)

If Tailscale is unavailable, start-host.ps1 falls back to a Cloudflare quick tunnel. Download the binary once:

.\get-cloudflared.ps1
.\start-host.ps1

Quick tunnels get a new random *.trycloudflare.com hostname whenever they restart. That is fine for testing, but you must re-paste the URL into the connector after a restart.

Add the connector in Claude

  1. + → Connectors → Add custom connector

  2. Name it image-gen (or anything you like)

  3. Paste the URL from connector-url.txt

  4. Authentication: No sign-in

  5. Leave request headers empty

  6. Transport: Streamable HTTP

  7. Click Add

The full URL is printed by start-host.ps1 and saved in connector-url.txt.

Tools

generate_image

Argument

Type

Description

prompt

string, required

Subject, setting, composition, lighting, style, constraints

size

string

1024x1024 (default), 1536x1024, 1024x1536, or square / landscape / portrait

filename

string

Optional base filename; the extension is chosen from the image data

backend

string

auto (default), codex, or pollinations

auto tries Codex first and falls back to FLUX if Codex fails. A call that takes longer than ~50 seconds returns a job_id instead of the image, because Claude Desktop cuts MCP calls at about 60 seconds.

get_image_job

Poll a job returned by generate_image.

Argument

Type

Description

job_id

string, required

The id returned by generate_image

wait_seconds

number

How long to wait, 1–45 seconds; default 30

Jobs expire after 10 minutes.

image_backend_status

Reports the output folder, Codex CLI version, login state, default backend, and fallback status.

Configuration

Environment variables read by server.mjs:

Variable

Default

Purpose

CODEX_BIN

codex

Path to the Codex executable

CLAUDE_IMAGE_DIR

~/Pictures/Claude Images

Output folder

IMAGE_BACKEND

auto

Default backend

CODEX_IMAGE_TIMEOUT_MS

240000

Codex process timeout

POLLINATIONS_TIMEOUT_MS

180000

FLUX request timeout

CODEX_SOFT_WAIT_MS

50000

Time before returning a job_id

MCP_TRANSPORT

stdio

Set to http to serve Streamable HTTP

MCP_HTTP_HOST

127.0.0.1

HTTP bind address

MCP_HTTP_PORT

8788

HTTP port

MCP_PATH_SECRET

generated

Override the secret path segment

You can also start HTTP mode directly:

node server.mjs --http

Endpoints:

  • POST /mcp/<secret> — MCP JSON-RPC

  • GET /health — health check

  • DELETE /mcp/<secret> — end an MCP session

The secret is written to http-secret.txt on first run. Treat it like a password.

Autostart on Windows

.\install-autostart.ps1

This adds a hidden launcher to the current user's Startup folder, so the server starts at login. Tailscale also starts with Windows. The stable Funnel URL becomes available a few seconds after login.

To stop everything:

.\stop-host.ps1

Security notes

  • The public endpoint is protected by an unguessable /mcp/<secret> path, not by OAuth.

  • Anyone with the full URL can spend the signed-in user's image quota. Do not share it.

  • The HTTP server rate-limits requests to 120 per minute per IP.

  • http-secret.txt, connector-url.txt, host-pids.json, logs, and tunnel binaries are git-ignored. Never commit them.

  • The Cloudflare fallback forwards prompts to Cloudflare and then to the local server. The FLUX fallback sends prompts to Pollinations.

  • This is a personal tool, not a multi-tenant production service.

Troubleshooting

codex login status says not signed in

codex login

Claude Code doesn't list the server

node install.mjs

Then start a new session. In Claude Code, /mcp must be the first thing typed in an empty prompt.

The connector URL stopped working

.\start-host.ps1

Then open https://your-machine.your-tailnet.ts.net/health in a browser. If it returns {"ok":true,...}, the server is fine; restart Claude Desktop. If it fails, check that Tailscale is running and signed in, and that Funnel is enabled:

tailscale status
tailscale funnel status

Long generations time out

The job handoff should handle it. If not, increase CODEX_SOFT_WAIT_MS or use get_image_job.

Files

  • server.mjs — MCP server (stdio + Streamable HTTP)

  • install.mjs — registers the stdio server in ~/.claude.json

  • start-host.ps1 — starts HTTP mode and publishes it (Tailscale Funnel, then Cloudflare fallback)

  • stop-host.ps1 — stops the server and tunnel

  • install-autostart.ps1 — adds the Windows login autostart entry

  • get-cloudflared.ps1 — downloads the Cloudflare Tunnel binary

  • commands/image.md — optional /image slash command for Claude Code

License

MIT. See LICENSE.

Available Tools

3 tools
generate_imageA

Generate an image from a text prompt and save it to disk. Uses the ChatGPT/Codex plan when signed in, otherwise a free FLUX backend. Returns the image and saved path, or a job_id when generation takes longer than ~50 seconds; in that case call get_image_job with the job_id.

Inputs: prompt (required), size, backend, filename.

get_image_jobA

Retrieve the image from a generate_image call that returned a job_id. Waits up to wait_seconds for the generation to finish.

Inputs: job_id (required), wait_seconds.

image_backend_statusA

Report whether the ChatGPT/Codex image backend is signed in, the free fallback, and the output folder.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: generate_image creates, get_image_job polls an async result, and image_backend_status reports configuration. The descriptions explicitly cross-link generate_image's job_id output to get_image_job, so an agent cannot easily misselect.

    Naming Consistency4/5

    All names use consistent snake_case, and two follow a verb_noun pattern (generate_image, get_image_job). image_backend_status is a noun-only diagnostic name, a minor deviation from the verb-first convention.

    Tool Count5/5

    Three tools is well-scoped for a focused image-generation server; the async job model genuinely justifies a separate retrieval tool, and the status tool is small but useful for diagnosing backend auth. No filler tools.

    Completeness3/5

    Core flow (generate, poll, check backend) is covered, but the async job lifecycle has dead ends: no way to list pending jobs, cancel a job, or recover a result if the job_id is lost. Configuration of output/size is also not exposed beyond what generate_image infers.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers