MCP OpenAI Images

A local MCP server (stdio) that lets Claude (or any MCP client) generate and edit images with the OpenAI Images API (GPT Image models) — from scratch, from up to 16 reference images, or with inpainting masks — and then crop them to exact sizes and overlay text using your real brand fonts.

Built for marketing pipelines: generate a master image for a topic, then derive per-channel pieces (blog, LinkedIn, Instagram, YouTube thumbnail, newsletter) from it so they stay visually consistent.

It runs locally on your Mac on purpose: cloud sandboxes (such as Cowork's) block egress to api.openai.com, while a local MCP server is reachable from Claude Code, Claude Desktop, and Cowork sessions through the remote-devices bridge.

Tools

Tool names and responses are in Spanish, since the server is used by Spanish-speaking agents.

Common parameters

Post-processing order: OpenAI image → crop_to → overlay_text (coordinates refer to the final image).

Related MCP server: image-studio-mcp

Requirements

• macOS (other platforms should work, but font lookup is tuned for macOS)

• Node.js 20 or later

• An OpenAI API key with access to GPT Image models

Installation

git clone https://github.com/Go-Business-Inc/MCP-OpenIA.git
cd MCP-OpenIA
npm install
npm run build
cp .env.example .env
chmod 600 .env

Put your key in .env as OPENAI_API_KEY=.... Never hardcode it, paste it into a chat, or store it in shared documents.

Brand fonts

overlay_text looks for font files in fonts/, ~/Library/Fonts, and /Library/Fonts. Drop the .ttf files of your brand typefaces into fonts/ (see fonts/README.md). If a font can't be found — or lacks a character in your text — the tool returns an error instead of silently substituting another typeface, and it checks the font before calling OpenAI, so no money is spent.

To add a font later, drop its files into fonts/ (or install it on the Mac) — no restart needed. For Google Fonts families, the agent can also call instalar_fuente_google with the family name (e.g. "Playfair Display"): it downloads the variable (or non-italic static) .ttf files and the license only from the official google/fonts repository, validates them, and makes them available immediately. The tool is described to the agent as usable only when the user explicitly requests a font, so it won't swap your brand typography on its own. Commercial fonts must be installed manually.

Text is drawn from the font file's glyph outlines (via fontkit), not through the system text renderer, so the result doesn't depend on which fonts are installed. Variable fonts are supported: fontWeight sets the wght axis and fontSize the opsz axis when present.

Registering the server

The server has to be registered in each Claude app that should use it. Claude Code and Claude Desktop keep separate configurations, so registering it in one doesn't make it available in the other.

Claude Code

claude mcp add --scope user openai-images -- node /absolute/path/to/MCP-OpenIA/dist/index.js

Then restart your Claude Code session and check that the tools are listed with /mcp.

Claude Desktop (and Cowork)

Claude Desktop reads its MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Cowork sessions reach local servers through Claude Desktop's remote-devices bridge, so registering the server here is what makes it available in Cowork too.

Option A — registration script (recommended)

1. Open Terminal.app (or iTerm). Don't use Claude Desktop's built-in terminal or ask Claude inside the app to run it: the script would be stopped when the app quits.

2. Run:

   cd /absolute/path/to/MCP-OpenIA
   ./scripts/register-claude-desktop.sh

3. Quit Claude Desktop with Cmd+Q (closing the window isn't enough).

The script waits for the app to quit, backs up the config (claude_desktop_config.json.bak-<timestamp>), adds the openai-images entry pointing at your node and dist/index.js, and reopens Claude Desktop. If the app isn't running, it registers right away. It gives up without changing anything if the app isn't quit within 30 minutes.

Optional environment variables: NODE_BIN (node binary to register, default: the node on your PATH), MCP_NAME (default openai-images), TIMEOUT_SECONDS (default 1800).

Option B — manual

1. Quit Claude Desktop completely (Cmd+Q).

2. Add the entry to ~/Library/Application Support/Claude/claude_desktop_config.json, keeping everything else in the file:

   {
     "mcpServers": {
       "openai-images": {
         "command": "/usr/local/bin/node",
         "args": ["/absolute/path/to/MCP-OpenIA/dist/index.js"]
       }
     }
   }

   Use the output of which node as command — Claude Desktop doesn't load your shell's PATH, so a bare node may not be found.

3. Open Claude Desktop again.

Verify

1. The entry is still in the config after the app has been open for a few minutes:

   grep -A3 '"openai-images"' ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. The app launched the server — this log file exists and shows no startup errors:

   tail -n 20 ~/Library/Logs/Claude/mcp-server-openai-images.log

3. In a new Cowork or chat session, ask Claude to run listar_modelos_imagen. It should list the image models your OpenAI key can use. Sessions that were already open when the server was registered won't see it.

Output

Every image is saved to output/YYYY-MM-DD/, and the response includes its file_path, dimensions, estimated cost, and a preview thumbnail.

To attach an image to another system, pass the file_path to a tool that uploads local files (for example, an upload_file_path tool in a Pipefy MCP server running on the same machine).

incluir_base64: true adds file_name + file_base64 to each image, but a base64-encoded image is millions of characters: MCP clients truncate large tool outputs (Claude Code's MAX_MCP_OUTPUT_TOKENS) and it fills the agent's context. Passing the file path is the recommended route.

Errors

The server never reports success without a real image. Failures return isError: true and a JSON payload with a tipo_error field:

Cost log

Each call appends one JSON line to logs/uso.jsonl: model, size, quality, n, token usage, estimated cost in USD, duration, and output files. Prices live in src/costs.ts (checked 2026-09-13 against OpenAI's pricing page) — update them if OpenAI changes its rates.

Troubleshooting

Configuration

Variables can go in .env (read from the project folder, not the working directory) or in the env block of your MCP client config.

Credits

Built by Go Business Inc.

Go Business Inc. helps companies transform their operations through digital automation: process-based CRM and sales pipelines, AI chatbots and agents, automated marketing journeys, customer self-service portals, business intelligence dashboards, hardware automation, and remote-work management.