image-gen
# 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](https://tailscale.com/) (preferred) or Cloudflare Tunnel
## Quick start (local stdio)
```powershell
npm install -g @openai/codex
codex login
```
Verify:
```powershell
codex login status
```
Clone the repo and register the server with Claude Code:
```powershell
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.
### Option A: Tailscale Funnel (stable URL, recommended)
1. Install Tailscale and sign in.
2. Enable Funnel for your tailnet when Tailscale asks (or in the admin console).
3. Run:
```powershell
.\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:
```powershell
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:
```powershell
.\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:
```powershell
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
```powershell
.\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:
```powershell
.\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**
```powershell
codex login
```
**Claude Code doesn't list the server**
```powershell
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**
```powershell
.\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:
```powershell
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](LICENSE).
TDQS
Scored across 3 tools
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.
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.
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.
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.