image-gen-mcp

Generate and edit images from your coding agent, with your own API keys. Ask for a blog cover, a logo tweak, or a placeholder illustration, and the file lands directly in your project where the agent can read it and iterate.

Google Gemini image models (the Nano Banana family) and OpenAI GPT image models behind one interface. Configure one provider or both.

_{This banner and the repository's social preview card were both generated by this server, with gemini-3.1-flash-image at 16:9 2K. Prompts are in assets/README.md.}

Install

claude mcp add image-gen --scope user \
  --env GEMINI_API_KEY=your-gemini-key \
  --env OPENAI_API_KEY=your-openai-key \
  -- npx -y @nuver-labs/image-gen-mcp

Start a new Claude Code session to pick it up, then check claude mcp list.

Three things that trip people up:

• At least one option must sit between the last --env and the server name. Above, --scope does that job. Put the name straight after an --env pair and the CLI reads it as another KEY=value.
• -- before the command is mandatory. Without it the server's own arguments get parsed as Claude Code's.
• Drop the --env line for any provider you do not use. You need at least one.

Get keys from Google AI Studio and the OpenAI platform.

Other clients

Same package everywhere. For .mcp.json (project scope, commit it) and Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "image-gen": {
      "command": "npx",
      "args": ["-y", "@nuver-labs/image-gen-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-key",
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

Claude Code also accepts a per-server "timeout": 600000, which Claude Desktop does not. Cursor uses the same shape in .cursor/mcp.json. On Windows, GUI hosts cannot always find npx, so use "command": "cmd" with "args": ["/c", "npx", "-y", "@nuver-labs/image-gen-mcp"].

Use it

Just ask, in plain language:

• "Generate a 16:9 hero image of a lighthouse at dusk and save it to assets/hero.png"
• "Take public/logo.png and give it a transparent background"
• "Create 3 variations of a flat paper airplane icon, square, into design/drafts/"

The agent calls generate_image or edit_image with an absolute output_path inside your project, the file lands on disk, and the agent can then read the saved path to look at the result and refine it. If a call fails, ask it to run list_capabilities to see what is actually configured.

Tools

generate_image

edit_image

Everything above, plus:

When output_path is omitted, the result is saved next to the first source image.

list_capabilities

No arguments. Reports configured providers as booleans (never key values), the default provider and models, known model options, the output directory fallback chain, and any directory restriction in force.

Configuration

With no output_path, files go to the first of: IMAGE_GEN_MCP_OUTPUT_DIR, CLAUDE_PROJECT_DIR (set by Claude Code, points at the current project), the server working directory.

Security

This server runs locally with your full user privileges and is not sandboxed by the MCP client. Worth understanding before you grant it blanket tool approval.

What it can do. Writes image files to disk. Reads the image files you point edit_image at. Sends your prompt, and any edit_image source image, to the provider you selected. Makes billable API calls. That is the whole surface: three tools, no shell execution, no arbitrary URL fetching, no telemetry.

File access. The model chooses output_path and source_paths, and by default they are unrestricted, because that is what makes the tool useful: your agent saves into whichever project you are working in. Note that Claude Code's working-directory boundary does not extend to MCP servers, and Anthropic does not security-audit third-party MCP servers.

To draw a hard boundary, set IMAGE_GEN_MCP_ALLOWED_DIRS:

IMAGE_GEN_MCP_ALLOWED_DIRS=/Users/you/projects,/Users/you/Desktop

Every output path and every edit_image source must then resolve inside one of those roots. Paths are compared after realpath resolution, so a symlink pointing out of a root is refused, and containment uses path segments rather than a string prefix, so a sibling directory like /Users/you/projects-private does not slip through. If none of the configured entries exist, the server refuses all file access rather than silently running unrestricted.

API keys. Keys are read only from the environment, passed to the provider SDK constructors, and used nowhere else. They are never logged, never written to the ledger, and never returned by list_capabilities, which reports booleans.

The risk is where you put them, not what this server does with them. Keys inlined into ~/.claude.json or claude_desktop_config.json sit in plaintext, readable by any process running as you, and an agent asked to read its own config can print them into a transcript. Prefer exporting from a shell profile or a secret manager, chmod 600 the config files, and use a dedicated key with a spend limit rather than a shared production key.

Spend. There is no built-in rate limit or cap. An agent in a retry loop can generate a lot of images quickly. Set OpenAI hard spend limits and Google Cloud budget alerts.

Local log. The ledger at ~/.image-gen-mcp/images.jsonl contains a truncated copy of each prompt in plaintext and grows without bound. Disable it with IMAGE_GEN_MCP_LOG_FILE=none, and do not commit it.

Prompt injection. Tool results re-enter the model's context. Prefer per-call approval over blanket-allowing this server, and glance at the output path and any edit_image source path when approving. Pin a version and review the diff before upgrading.

Found a vulnerability? See SECURITY.md. Please do not open a public issue.

Logging

Every successful call records one structured JSON entry, two ways:

• stderr, always: one [image-gen-mcp] image {...} line, visible in /mcp output and Claude Code logs.
• JSONL ledger, on by default: the same JSON appended to ~/.image-gen-mcp/images.jsonl, one line per call. Ledger write failures never break a generation, they warn once on stderr.

Each entry captures the provider, model, requested size, elapsed seconds, a truncated prompt with its full character count, token usage when the provider reports it, and per-image details: saved path, byte size, human-readable size, mime type, and actual pixel dimensions.

tail -n 20 ~/.image-gen-mcp/images.jsonl
jq 'select(.usage) | .usage.totalTokens' ~/.image-gen-mcp/images.jsonl

Costs

Every call hits a paid API, typically cents per image, varying by provider, model, quality, and size. Cheap options for drafts: OpenAI quality: low (roughly $0.006 for a low-quality 1024x1024 on gpt-image-2) or gpt-image-1-mini, and Gemini gemini-3.1-flash-lite-image. Gemini's gemini-2.5-flash-image may have a free tier on unbilled keys, so IMAGE_GEN_MCP_GEMINI_MODEL=gemini-2.5-flash-image makes it the default.

Timeouts

Generation takes roughly 10 to 120 seconds depending on model and size. Claude Code's defaults are generous and this server sends progress notifications during long calls, so no tuning is normally needed. If you set a tight global MCP_TOOL_TIMEOUT, add a per-server "timeout": 600000 in .mcp.json.

Troubleshooting

• Server logs go to stderr with an [image-gen-mcp] prefix. Claude Code surfaces them in /mcp output and its logs.
• Registered but no tools: start a new session, then check claude mcp list and claude mcp get image-gen.
• Provider 'x' is not configured: that key is missing from the MCP server environment. Re-register with the --env flag or edit your config.
• Output is outside the allowed directories: IMAGE_GEN_MCP_ALLOWED_DIRS is set. Run list_capabilities to see the roots.
• Response too large: return_image inlines a full image and can exceed the MCP output token limit (MAX_MCP_OUTPUT_TOKENS, default 25k). Leave it off and let the agent read the saved file.
• Gemini refusal: the error includes the finish reason and any provider text. Rephrase the prompt.

Build from source

Requires Node 22+ and pnpm.

git clone https://github.com/nuver-labs/image-gen-mcp.git
cd image-gen-mcp
pnpm install
pnpm build

Then point your client at node /abs/path/to/image-gen-mcp/dist/index.js instead of npx -y @nuver-labs/image-gen-mcp.

pnpm test      # unit tests, no API keys needed
pnpm inspect   # list the tools over real MCP stdio

# Live tests. These cost real API credits.
GEMINI_API_KEY=... node dist/smoke.js --provider gemini
OPENAI_API_KEY=... node dist/smoke.js --provider openai
node dist/smoke.js --provider gemini --edit ./smoke-output/smoke-gen-gemini.png

Contributing

Bug reports, provider quirk fixes, and documentation improvements are welcome. See CONTRIBUTING.md. For anything larger, open an issue first.

Planned: OpenAI mask and inpainting support, migration off the legacy Gemini generateContent image path to the Interactions API, and more providers.

License

MIT

Built by Nuver Labs.