gpt-mcp

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

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:

OPENAI_API_KEY=sk-... npm run inspect

Register it with Claude

Claude Code (CLI):

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:

{
  "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).