image-studio-mcp

中文：image-studio-mcp 是一个本地 stdio MCP server，带 Codex 插件元数据和配套 skill，用来调用 OpenAI 兼容图片接口，完成生图和改图。
English: image-studio-mcp is a local stdio MCP server with Codex plugin metadata and a companion skill for image generation and image editing through OpenAI-compatible image APIs.

Repository:

• https://github.com/jhupo/image-studio-mcp.git

Features

• generate_image for text-to-image

• edit_image for image edits, multi-image edits, and optional mask edits

• image_studio_doctor for connectivity and configuration checks

• Configurable OPENAI_BASE_URL

• Configurable OPENAI_API_KEY

• Configurable OPENAI_IMAGE_MODEL

• Local file output

• Codex plugin metadata plus skill

Requirements

• Node.js 20+

• An API key for an OpenAI-compatible image endpoint

Environment Variables

• OPENAI_API_KEY 中文：必填，图片接口用到的 key。
  English: Required. API key for the image endpoint.

• OPENAI_BASE_URL 中文：可选，默认是 https://api.openai.com/v1。
  English: Optional. Defaults to https://api.openai.com/v1.

• OPENAI_IMAGE_MODEL 中文：可选，默认是 gpt-image-2。
  English: Optional. Defaults to gpt-image-2.

• OPENAI_IMAGE_TIMEOUT_MS 中文：可选，默认 240000，代理慢或上游慢时可以调大。
  English: Optional. Defaults to 240000. Increase it if your gateway or upstream image model is slow.

Local Setup

npm install
npm run validate

node ./scripts/openai-image-mcp.mjs

Helpful commands:

npm run doctor

npm run smoke:test

中文：这个 server 用的是 stdio transport，通常由 MCP 宿主拉起，不是手工常驻运行。
English: This server uses stdio transport and is normally launched by an MCP host instead of being run manually.

What image_studio_doctor Checks

中文：

• 当前宿主是否已经能调用这个 MCP server

• 当前 server 进程是否拿到了 OPENAI_API_KEY

• 当前 OPENAI_BASE_URL

• 当前 OPENAI_IMAGE_MODEL

• /models 是否可达

• 网关返回了哪些模型

• 配置中的模型是否出现在 /models 结果里

English:

• whether the current host can already call this MCP server

• whether the server process can see OPENAI_API_KEY

• which OPENAI_BASE_URL is active

• which OPENAI_IMAGE_MODEL is configured

• whether /models is reachable

• which models the gateway reports

• whether the configured model appears in /models

中文：如果你想做一次真实、计费的端到端探测，可以在调用 image_studio_doctor 时传 probe_generation=true。
English: If you want a real billable end-to-end probe, call image_studio_doctor with probe_generation=true.

Install In Codex

This repo already includes:

• .codex-plugin/plugin.json

• .mcp.json

• skills/image-studio-mcp/SKILL.md

To install into another Codex workspace:

1. Copy the image-studio-mcp folder into the target workspace plugins/ directory.

2. Run npm install inside that plugin directory.

3. Set OPENAI_API_KEY in the local MCP configuration.

4. Optionally adjust OPENAI_BASE_URL and OPENAI_IMAGE_MODEL.

5. Make sure the marketplace entry points to ./plugins/image-studio-mcp.

6. Restart Codex if the plugin was added while the app was already open.

Why It May Not Show In Codex MCP Settings

中文：Codex 里“设置 -> MCP 服务器”通常看的是全局 ~/.codex/config.toml 里的 [mcp_servers.*]，不一定会显示插件目录里的 .mcp.json。
English: In Codex, “Settings -> MCP servers” usually reflects global [mcp_servers.*] entries from ~/.codex/config.toml, not necessarily plugin-local .mcp.json files.

中文：所以“插件能加载”不等于“它会出现在全局 MCP 列表里”。
English: That means “plugin installed” is not always the same as “visible in the global MCP settings list”.

Install In Any MCP Host

Any host that supports standard MCP stdio transport can use this project.

Example config:

{
  "mcpServers": {
    "image-studio-mcp": {
      "command": "node",
      "args": [
        "C:/absolute/path/to/image-studio-mcp/scripts/openai-image-mcp.mjs"
      ],
      "cwd": "C:/absolute/path/to/image-studio-mcp",
      "env": {
        "OPENAI_API_KEY": "your_api_key_here",
        "OPENAI_BASE_URL": "https://dash.classicriver.cn/v1/",
        "OPENAI_IMAGE_MODEL": "gpt-image-2"
      }
    }
  }
}

Copyable example:

• mcp.config.example.json

Minimal Usage Examples

Official OpenAI-Compatible Example

{
  "prompt": "a glossy orange sports car under studio lights",
  "output_dir": "C:/workspace/output",
  "filename_prefix": "sports-car",
  "count": 1,
  "size": "1024x1024",
  "output_format": "png"
}

Compatible Proxy Example

{
  "prompt": "a cyberpunk city girl with neon signs and rainy streets",
  "output_dir": "C:/workspace/output",
  "filename_prefix": "cyberpunk-girl",
  "count": 1,
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png"
}

Edit Example

{
  "prompt": "keep the subject, change the clothes to silver sci-fi armor",
  "input_images": [
    "C:/workspace/input/original.png"
  ],
  "output_dir": "C:/workspace/output",
  "filename_prefix": "armor-edit",
  "output_format": "png"
}

How To Use It In Codex

中文：

• 可以直接说“给我生成一张图”。

• 更稳的说法是同时告诉它：

  • 生成什么

  • 输出到哪里

  • 要不要多张

  • 是生图还是改图

• 如果是第一次装好、第一次调用、或者刚切换代理，先让它跑 image_studio_doctor。

• 如果当前宿主只有 skill 文本、没有真实 MCP 工具入口，模型应该明确告诉你“只检测到 skill，没有检测到可调用工具”，而不是假装自己能直接出图。

English:

• You can simply say “generate an image for me”.

• It is more reliable to also specify:

  • what to generate

  • where to save it

  • whether you want multiple variants

  • whether this is text-to-image or image editing

• If this is the first call after installation, the first call after switching proxies, or a previously failed setup, run image_studio_doctor first.

• If the host only loaded the skill text but did not expose the actual MCP tools, the model should say that clearly instead of pretending image generation is callable.

Context Memory In Codex

中文：

• 会记住，但主要是当前对话线程里的上下文，不是永久记忆。

• 新对话、上下文压缩、重启后，之前的图片任务细节可能不在。

• 最稳的做法是让图片保存到明确路径，并在后续继续引用那个路径。

English:

• Yes, but mostly within the current conversation thread, not as permanent memory.

• After a new thread, context compaction, or a restart, earlier image-task details may no longer be available.

• The safest pattern is to save outputs to a clear path and refer to that path again later.

Tools

image_studio_doctor

中文：做安装后自检、配置排查、代理排查。
English: Runs installation, configuration, and proxy troubleshooting checks.

Important inputs:

• probe_generation

• probe_prompt

• models_preview_limit

generate_image

中文：根据提示词生成一张或多张图片。
English: Generates one or more images from a prompt.

Important inputs:

• prompt

• output_dir

• filename_prefix

• count

• size

• quality

• background

• output_format

edit_image

中文：基于一张或多张已有图片进行改图。
English: Edits one or more existing source images from a prompt.

Important inputs:

• prompt

• input_images

• mask_image

• output_dir

• filename_prefix

• count

• size

• quality

• background

• output_format

Error Guide

• 401 invalid_api_key 中文：认证失败，通常是 key 不对、key 对这个代理不可用、或者上游没有授权。
  English: Authentication failed. The key is wrong, not valid for this gateway, or lacks upstream access.

• 404 中文：路径大概率不对，常见原因是 OPENAI_BASE_URL 没写到 /v1。
  English: Usually a path problem. A common cause is OPENAI_BASE_URL not ending at /v1.

• 429 中文：代理或上游限流了。
  English: The proxy or upstream account is rate-limited.

• 524 中文：代理等上游太久超时了。
  English: The proxy timed out while waiting for the upstream image job.

• No available compatible accounts 中文：代理当前没有可用的图像账号资源。
  English: The proxy currently has no available upstream image accounts.

• HTML instead of JSON 中文：通常说明 OPENAI_BASE_URL 指到了网页，不是 API。
  English: Usually means OPENAI_BASE_URL points to a dashboard page, not an API endpoint.

Security Note

中文：不要把真实 key 提交进 Git，也不要到处手填进命令历史。优先通过 MCP 宿主的环境变量或本地私有配置注入。
English: Do not commit a real key into Git and avoid pasting it into shell history. Prefer environment variables or private local host configuration.

Validation

node --check ./scripts/openai-image-mcp.mjs

npm run validate

npm run doctor

npm run smoke:test

Skill validation:

python C:/Users/Administrator/.codex/skills/.system/skill-creator/scripts/quick_validate.py ./skills/image-studio-mcp