Content
# OpenAI image mcp
MCP server for OpenAI **gpt-image** models — generate, edit, and multi-turn edit
images straight from Claude (or any MCP client).
## Tools
- `generate_image` — text → image(s)
- `edit_image` — edit / extend / compose with an optional mask
- `edit_image_conversation` — multi-turn iterative edit (Responses API)
- `image_capabilities` — discover models, params, pricing as-of date
---
## Quick start
### 1. Get the code & build
```bash
git clone <repo-url> openai-image-mcp
cd openai-image-mcp
npm install
npm run build
```
`npm run build` produces `dist/index.js` — the entrypoint you point Claude at.
### 2. Register with Claude Code (one command)
```bash
claude mcp add openai-image --scope user \
--env OPENAI_API_KEY=sk-your-openai-api-key \
--env IMAGE_OUTPUT_DIR=/absolute/path/to/images \
-- node /absolute/path/to/openai-image-mcp/dist/index.js
```
- Use an **absolute** path to `dist/index.js` (output of step 1).
- `IMAGE_OUTPUT_DIR` is where generated images are written. Optional — defaults to
`~/Pictures/openai-image-mcp`.
- `--scope user` makes it available in every project. Use `--scope project` to limit
it to the current repo.
Verify it registered:
```bash
claude mcp list
```
### 3. Use it
In Claude, just ask — e.g. *"generate an image of a red bicycle on the beach"*.
The server writes the file under `IMAGE_OUTPUT_DIR` and returns the path.
---
## Configuration (env vars)
| Var | Required | Default | Purpose |
|-----|----------|---------|---------|
| `OPENAI_API_KEY` | **yes** | — | OpenAI API key |
| `IMAGE_OUTPUT_DIR` | no | `~/Pictures/openai-image-mcp` | where images are saved |
| `DEFAULT_MODEL` | no | `gpt-image-2` | gpt-image-1 / gpt-image-1-mini / gpt-image-2 |
| `DEFAULT_OUTPUT_MODE` | no | `path` | `path` \| `base64` \| `both` |
| `MAX_COST_PER_CALL_USD` | no | — | reject a call whose estimate exceeds this |
| `CONFIRM_ABOVE_N` | no | — | require `confirm:true` when generating more than N images |
| `ALLOW_URL_INPUT` | no | `false` | allow image inputs given as URLs (see Security) |
| `SPEND_LOG_PATH` | no | — | append per-call cost records as JSONL |
| `PROMPT_ENHANCE` | no | `false` | locally augment short prompts (no extra LLM call) |
| `OPENAI_BASE_URL` | no | — | override API base URL |
| `LOG_LEVEL` | no | `info` | `debug` \| `info` \| `warn` \| `error` |
Add any of these as extra `--env KEY=value` flags on the `claude mcp add` command.
---
## Manual MCP config (other clients)
If your client uses a JSON config (Claude Desktop, Cursor, VSCode), add:
```json
{
"mcpServers": {
"openai-image": {
"command": "node",
"args": ["/absolute/path/to/openai-image-mcp/dist/index.js"],
"env": {
"OPENAI_API_KEY": "sk-your-openai-api-key",
"IMAGE_OUTPUT_DIR": "/absolute/path/to/images"
}
}
}
}
```
---
## Security notes
- URL image input is **off by default**. Set `ALLOW_URL_INPUT=true` to enable. When on,
fetches resolve all DNS addresses and reject any private / loopback / link-local /
CGNAT / IPv4-mapped target, re-validating on every redirect hop (SSRF guard).
- Output paths are confined to `IMAGE_OUTPUT_DIR`; existing files are never overwritten
(a numeric suffix is added on collision).
- Logs go to **stderr** only; stdout is reserved for the MCP protocol.
---
## Development
```bash
npm test # run the vitest suite
npm run typecheck # tsc --noEmit
npm run build # compile to dist/
```
## Notes
- Models: gpt-image-1 (deprecating 2026-10-23), gpt-image-1-mini, gpt-image-2 (default).
- DALL-E was removed from the OpenAI API (2026-05-12) — not supported.
- Pricing data is as of 2026-06; query the `image_capabilities` tool for details.
