# image-gen-mcp

MCP server (stdio, Node >= 18) that exposes one tool, `generate_image`, backed by any
OpenAI-compatible `images/generations` endpoint. Images are saved to disk and returned
inline, so the model can see the result. Ships with a Claude Code skill (`skills/image-gen`)
and can be installed as a Claude Code plugin.

## Configuration

All configuration is through environment variables.

| var | required | default | meaning |
|-----|----------|---------|---------|
| `IMAGE_ENDPOINT` | yes | | Full URL of `.../images/generations` |
| `IMAGE_API_KEY` | yes | | API key |
| `IMAGE_MODEL` | yes | | Model or deployment name |
| `IMAGE_AUTH_HEADER` | no | `api-key` | `api-key`, or `Authorization` (sends `Bearer <key>`) |
| `IMAGE_OUT_DIR` | no | `~/Pictures/image-gen` | Output folder |

If a required variable is missing the server still starts; the tool call returns an error naming the missing variables.

### Azure AI Foundry

    IMAGE_ENDPOINT=https://<resource>.services.ai.azure.com/openai/v1/images/generations
    IMAGE_MODEL=<deployment name>
    IMAGE_API_KEY=<key of that resource>

### OpenAI

    IMAGE_ENDPOINT=https://api.openai.com/v1/images/generations
    IMAGE_MODEL=gpt-image-1
    IMAGE_AUTH_HEADER=Authorization
    IMAGE_API_KEY=sk-...

## Install

Requires Node >= 18 and `git` (npx fetches the package from GitHub).

### As a plugin (server + skill, recommended)

    /plugin marketplace add IlTeo285/image-gen-mcp
    /plugin install image-gen@image-gen-mcp

The server reads the variables above from the environment Claude Code was started from,
so set them (or launch through a secret manager) before starting `claude`.

### MCP server only

    claude mcp add image-gen --scope user \
      -e IMAGE_ENDPOINT=... -e IMAGE_API_KEY=... -e IMAGE_MODEL=... \
      -- npx -y github:IlTeo285/image-gen-mcp

Passing the key with `-e` stores it in plain text in `~/.claude.json`. Prefer the secret-manager
approach below and omit `-e`. This route does not install the skill: copy `skills/image-gen/`
into `~/.claude/skills/image-gen/`.

To keep the key out of config files, launch Claude Code through a secret manager, for example
`op run --env-file=image-gen.env -- claude` with 1Password.

## Tool

`generate_image(prompt, size?, n?, filename?)`

- `size`: default `1024x1024`, passed through to the API.
- `n`: 1-4.
- `filename`: optional base name. Existing files are never overwritten.

Files are named `YYYYMMDD-HHMMSS-<slug>.<ext>`; the extension follows the API's `output_format`.

## Development

    npm install
    npm test

Tests use `node:test` with a mocked `fetch`, plus one real stdio handshake against `src/index.js`.

## Security

The API key is read from the environment only. It is never logged, and it is redacted from error messages.