Skip to main content
Glama
deenesjakoruzh
jhupo

image-studio-mcp

by jhupo
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Hybrid

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:

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

Available Tools

2 tools
edit_imageB

Edit one or more source images with a prompt, optionally using a mask, and save the results to local files.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes
input_imagesYes
output_dirYes
mask_imageNo
filename_prefixNo
countNo
sizeNo
qualityNo
backgroundNo
output_formatNo
output_compressionNo
userNo

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions the basic operation (edit with prompt, optionally mask, save locally), it lacks critical details such as whether this is a read-only or destructive operation, what permissions or authentication might be required, rate limits, error handling, or what the output looks like (e.g., file paths, success indicators). For a tool with 12 parameters and no annotations, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that efficiently conveys the core functionality. It's front-loaded with the main action and includes key optional elements without unnecessary elaboration. Every word earns its place, making it highly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (12 parameters, no annotations, no output schema), the description is incomplete. It doesn't explain the behavioral aspects (e.g., mutation effects, error handling), most parameter meanings, or what the tool returns (since there's no output schema). For a tool with this level of complexity, the description should provide more guidance to help an agent use it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning none of the 12 parameters have descriptions in the schema. The description only mentions 'prompt', 'mask', and saving to 'local files', which loosely corresponds to 'prompt', 'mask_image', and 'output_dir' parameters. It doesn't explain the purpose or usage of the other 9 parameters (e.g., 'count', 'size', 'quality', 'user'), leaving them undocumented. With low coverage, the description fails to compensate adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('edit'), the target ('one or more source images'), the mechanism ('with a prompt'), and the outcome ('save the results to local files'). It distinguishes from the sibling 'generate_image' by specifying editing of existing images rather than generation from scratch. However, it doesn't specify the type of editing (e.g., inpainting, style transfer) which could make it more specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for editing existing images with a prompt, which differentiates it from 'generate_image' that presumably creates new images. However, it doesn't provide explicit guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or constraints beyond the optional mask parameter.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_imageC

Generate one or more images from a prompt with an OpenAI-compatible image endpoint and save them to local files.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes
output_dirYes
filename_prefixNo
countNo
sizeNo
qualityNo
backgroundNo
moderationNo
output_formatNo
output_compressionNo
userNo

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions saving to local files but doesn't cover critical aspects like rate limits, authentication needs, error handling, or what happens if files already exist. For an 11-parameter tool with no annotation coverage, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-constructed sentence that efficiently conveys the core functionality without unnecessary words. It's appropriately sized and front-loaded with the essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (11 parameters, no annotations, no output schema), the description is inadequate. It covers the basic purpose but lacks parameter explanations, behavioral context, usage guidelines, and output information. For a sophisticated image generation tool, this leaves too many unanswered questions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage for 11 parameters, the description must compensate but fails to do so. It mentions 'prompt' and 'output_dir' implicitly through the action description but doesn't explain any of the other 9 parameters like 'size', 'quality', 'background', etc. This leaves most parameters semantically undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('generate') and resource ('images'), specifying it uses an OpenAI-compatible endpoint and saves to local files. It distinguishes from the sibling 'edit_image' by focusing on generation rather than editing. However, it doesn't explicitly contrast with the sibling tool, so it's not a perfect 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'edit_image'. It mentions the general context of generating images from prompts but offers no explicit when/when-not instructions or prerequisites for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.1/5.0
Disambiguation5/5

The two tools have clearly distinct purposes: edit_image modifies existing images based on a prompt and optional mask, while generate_image creates new images from scratch using a prompt. There is no overlap or ambiguity between these functions.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern (edit_image, generate_image) with the same verb style and underscore separation. The naming is perfectly predictable and uniform.

Tool Count2/5

With only 2 tools, this server feels thin for an 'image studio' domain. While the tools cover basic generation and editing, there are likely missing operations like image analysis, format conversion, or batch processing that would be expected in a comprehensive image toolset.

Completeness2/5

For an image processing server, there are significant gaps in the surface. Missing are tools for tasks like image resizing, filtering, metadata reading, format conversion, or batch operations. The current tools only cover generation and basic editing, leaving many common image workflows unsupported.

Maintenance

ActivityNo data
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jhupo/image-studio-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server