GPT Image MCP Server
This server provides AI agents with focused access to GPT Image generation capabilities via RunAPI, supporting image creation, editing, task management, and pricing lookups.
text_to_image: Generate images from a text prompt using thegpt-image-1.5model, with control over quality (mediumorhigh) and aspect ratio (1:1,2:3, or3:2).edit_image: Submit source image URLs along with a prompt to produce edited/modified images, with the same quality and aspect ratio options.get_task: Fetch the current status and result payload for a previously created task using its task ID.check_pricing: Retrieve the current pricing snapshot for the GPT Image model line, optionally filtered by model variant or endpoint.
Additional options:
Both
text_to_imageandedit_imagesupport awaitparameter — set totrueto poll until the task completes and receive output URLs immediately, orfalseto get just the task ID and check back later.Polling behavior is configurable via
timeout_msandpoll_interval_msparameters.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GPT Image MCP Server Create a text-to-image of a futuristic city skyline."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Why This Package?
@runapi.ai/gpt-image-mcp is a focused Model Context Protocol server for the GPT Image model line on RunAPI.
It gives MCP-compatible assistants direct access to 2 endpoints and 1 model variant without loading the full RunAPI catalog.
Use this per-model server when an agent should stay scoped to GPT Image. Use @runapi.ai/mcp when one assistant should discover every RunAPI model line.
Related MCP server: grok-imagine-mcp
Install
Add it to Claude Code:
claude mcp add gpt-image -s user -- npx -y @runapi.ai/gpt-image-mcpUse project scope when the server should be shared with a repository:
claude mcp add gpt-image -s project -- npx -y @runapi.ai/gpt-image-mcpCodex, Cursor, Windsurf, VS Code, Roo Code, and other MCP hosts can use the same stdio command:
{
"mcpServers": {
"gpt-image": {
"command": "npx",
"args": ["-y", "@runapi.ai/gpt-image-mcp"]
}
}
}check_pricing works before sign-in. For task creation and status polling, ask your assistant to call the login tool. It opens a browser login and saves credentials to ~/.config/runapi/config.json, the same file used by runapi login.
Headless and CI hosts can still set RUNAPI_API_KEY before starting the MCP host.
Ready-made examples are in examples/ for Claude, Cursor, Windsurf, VS Code, and Roo Code.
Tools
Tool | Auth | Purpose |
| Yes | Create a GPT Image edit image task and optionally wait for a terminal status. Returns the task id, status, and output URLs. |
| Yes | Create a GPT Image text to image task and optionally wait for a terminal status. Returns the task id, status, and output URLs. |
| Yes | Fetch the current status and latest payload for an existing task. |
| No | Look up current pricing for a GPT Image model and endpoint. |
Models
GPT Image covers 1 model variant across 2 endpoints. Each tool accepts the models listed for it:
Tool | Models |
|
|
|
|
Model availability can change between releases. Use check_pricing or the GPT Image model page for the current catalog view.
Agent Prompts
Ask your assistant in natural language; it can inspect pricing, create the task, and return the task id plus output URLs.
Create a task
Run a GPT Image edit image task with RunAPI.The assistant can call check_pricing, then edit_image, and return the task id, status, and output URLs.
Submit without waiting
Create the task but don't wait for it to finish.The assistant calls the create tool with wait: false and returns the task id. Check on it later with get_task.
Check pricing before creating
Check current GPT Image pricing, then create the task if it matches my request.The assistant calls check_pricing and can link to the GPT Image model page for the canonical catalog entry.
Configuration
The server resolves auth in this order:
RUNAPI_API_KEYenvironment variable, useful for headless and CI hosts~/.config/runapi/config.json, created by the MCPlogintool orrunapi loginNo key, which still allows
check_pricing
The config file is normally managed by login. A pre-provisioned headless config can use:
{
"apiKey": "your_runapi_key"
}Do not commit real API keys.
Links
Resource | URL |
GPT Image model page | |
npm package | |
GitHub repository | |
RunAPI MCP overview | |
RunAPI docs |
License
Licensed under the Apache License, Version 2.0.
Available Tools
5 toolscheck_pricingC
Look up RunAPI pricing for the gpt-image model line.
Inputs: model, action.
edit_imageB
Create a GPT Image task on RunAPI (edit image). Returns a task id, status, and output URLs.
Inputs: prompt (required), quality (required), aspect_ratio (required), source_image_urls (required), +5 more.
get_taskB
Fetch the current status and latest result payload for a gpt-image task.
Inputs: action (required), task_id (required).
loginA
Authenticate RunAPI by opening a browser PKCE login flow and saving the API key to ~/.config/runapi/config.json.
Inputs: force.
text_to_imageB
Create a GPT Image task on RunAPI (text to image). Returns a task id, status, and output URLs.
Inputs: prompt (required), quality (required), aspect_ratio (required), wait, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct action: authentication, two clearly separated generation modes (edit vs text-to-image), task polling, and pricing lookup. There is no overlap between edit_image and text_to_image since their purposes are explicitly differentiated.
Names are consistently snake_case verb_noun (edit_image, text_to_image, get_task, check_pricing), which is predictable. The lone deviation is 'login', a bare verb that breaks the otherwise uniform pattern.
Five tools is well-scoped for a focused image-generation service. Each tool earns its place: auth, two task-creation paths, polling, and cost lookup.
The core lifecycle (login -> create task -> poll result) plus pricing is covered. Minor gaps exist: no task listing, cancellation, or deletion, but these are workarounds an agent can live without for the primary generation workflow.
Maintenance
Related MCP Connectors
Generate and edit images, create videos, quote credit costs, and retrieve private results.
Make images and videos, price requests, list AI models and read your balance, from one API key.
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
Generate and edit images (PNG, transparent, GIF, SVG) with GPT Image and Nano Banana models.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables image generation and editing using OpenAI's GPT Image API (gpt-image-1, 1.5, 2) with support for multi-image generation, history management, and batch processing.12855 npm1MIT
- AlicenseBqualityBmaintenanceEnables AI image and video generation tasks (text-to-image, image-to-video, edit, upscale, etc.) via RunAPI, with support for polling and pricing lookups.1084 npm1Apache 2.0
- AlicenseAqualityBmaintenanceEnables image editing, remixing, and text-to-image generation using Qwen 2 models via RunAPI. Supports task polling and pricing checks.5109 npmApache 2.0
- AlicenseBqualityBmaintenanceEnables background removal and upscaling of images using Recraft models via RunAPI, with task polling and pricing lookup.553 npmApache 2.0