# gpt-mcp

A tiny **local MCP server** that lets Claude generate images with the OpenAI API.

It runs on **your machine**, so it reaches OpenAI over *your* network — which is why it works even though Claude's own sandbox can't call `api.openai.com` directly.

## Two tools (on purpose)

Both generate an image the same way; they differ only in how the result comes back, so you can compare:

| Tool | Returns | Best for | Tradeoff |
|------|---------|----------|----------|
| `generate_image_to_file` | A **file path** (writes the PNG to disk) | Real, full-res assets | Lossless, cheap on context. Claude reads the file from disk. |
| `generate_image_bytes` | The **image inline** (base64 image block) | Small previews / icons | Claude *sees* it immediately, but can't perfectly re-save large images, and big files are heavy to pass. |

Rule of thumb: use `generate_image_to_file` for anything you want to keep; use `generate_image_bytes` to eyeball a quick result.

## Setup

```bash
cd gpt-mcp
npm install
```

Get an API key from https://platform.openai.com/api-keys. For local testing you can copy `.env.example` → `.env` and paste it in. In Cowork / Claude Code you instead pass it via the server config (below).

### Test it standalone (optional)

The MCP Inspector gives you a UI to call the tools directly:

```bash
OPENAI_API_KEY=sk-... npm run inspect
```

## Register it with Claude

**Claude Code (CLI):**

```bash
claude mcp add gpt-mcp \
  -e OPENAI_API_KEY=sk-your-key \
  -e GPT_MCP_OUTPUT_DIR="/Users/kavindu/Documents/Claude/Projects/personal finance tracker/financial-app/src/assets" \
  -- node "/Users/kavindu/Documents/Claude/Projects/personal finance tracker/gpt-mcp/src/index.js"
```

**Config file (Cowork / Claude Desktop / any MCP client)** — add under `mcpServers`:

```json
{
  "mcpServers": {
    "gpt-mcp": {
      "command": "node",
      "args": [
        "/Users/kavindu/Documents/Claude/Projects/personal finance tracker/gpt-mcp/src/index.js"
      ],
      "env": {
        "OPENAI_API_KEY": "sk-your-key",
        "GPT_MCP_OUTPUT_DIR": "/Users/kavindu/Documents/Claude/Projects/personal finance tracker/financial-app/src/assets"
      }
    }
  }
}
```

After it's connected, Claude can call `generate_image_to_file` / `generate_image_bytes`.

## Parameters

Both tools accept:

- `prompt` (required) — what to draw.
- `size` — `1024x1024` · `1536x1024` · `1024x1536` · `auto` (default `auto`).
- `quality` — `low` · `medium` · `high` · `auto` (default `auto`; higher = more cost).
- `background` — `transparent` · `opaque` · `auto`. Use `transparent` for logos/icons.
- `output_format` — `png` · `webp` · `jpeg` (default `png`).

`generate_image_to_file` additionally accepts:

- `filename` — name without extension (default: a slug of the prompt + timestamp).
- `output_dir` — where to save (default: `GPT_MCP_OUTPUT_DIR`, else `./generated-images`).

## Environment variables

| Var | Required | Purpose |
|-----|----------|---------|
| `OPENAI_API_KEY` | yes | Your OpenAI key. |
| `OPENAI_IMAGE_MODEL` | no | Defaults to `gpt-image-1`. |
| `GPT_MCP_OUTPUT_DIR` | no | Default save folder for `generate_image_to_file`. |

## Notes

- Images cost money on your OpenAI account (billed per image, higher quality costs more).
- The server only logs to **stderr** — stdout is reserved for the MCP protocol.
- `node` 18+ required (uses built-in `fetch`).