Skip to main content
Glama
README.md
# 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

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