Skip to main content
Glama
deenesjakoruzh
jhupo

image-studio-mcp

by jhupo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

image-studio-mcp

中文：image-studio-mcp 是一个本地 stdio MCP server，带 Codex 插件元数据和配套 skill，用来调用 OpenAI 兼容图片接口，完成生图和改图。
English: image-studio-mcp ist ein lokaler stdio MCP-Server mit Codex-Plugin-Metadaten und einer begleitenden Skill für die Bildgenerierung und Bildbearbeitung über OpenAI-kompatible Bild-APIs.

Repository:

Funktionen

  • generate_image für Text-zu-Bild

  • edit_image für Bildbearbeitungen, Multi-Bild-Bearbeitungen und optionale Maskenbearbeitungen

  • image_studio_doctor für Konnektivitäts- und Konfigurationsprüfungen

  • Konfigurierbare OPENAI_BASE_URL

  • Konfigurierbarer OPENAI_API_KEY

  • Konfigurierbares OPENAI_IMAGE_MODEL

  • Lokale Dateiausgabe

  • Codex-Plugin-Metadaten plus Skill

Anforderungen

  • Node.js 20+

  • Ein API-Schlüssel für einen OpenAI-kompatiblen Bild-Endpunkt

Umgebungsvariablen

  • OPENAI_API_KEY 中文：必填，图片接口用到的 key。
    English: Erforderlich. API-Schlüssel für den Bild-Endpunkt.

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

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

  • OPENAI_IMAGE_TIMEOUT_MS 中文：可选，默认 240000，代理慢或上游慢时可以调大。
    English: Optional. Standard ist 240000. Erhöhen Sie diesen Wert, wenn Ihr Gateway oder das Upstream-Bildmodell langsam ist.

Lokale Einrichtung

npm install
npm run validate
node ./scripts/openai-image-mcp.mjs

Hilfreiche Befehle:

npm run doctor
npm run smoke:test

中文：这个 server 用的是 stdio transport，通常由 MCP 宿主拉起，不是手工常驻运行。
English: Dieser Server verwendet den stdio-Transport und wird normalerweise von einem MCP-Host gestartet, anstatt manuell im Hintergrund zu laufen.

Was image_studio_doctor prüft

中文：

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

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

  • 当前 OPENAI_BASE_URL

  • 当前 OPENAI_IMAGE_MODEL

  • /models 是否可达

  • 网关返回了哪些模型

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

English:

  • ob der aktuelle Host diesen MCP-Server bereits aufrufen kann

  • ob der Server-Prozess den OPENAI_API_KEY sehen kann

  • welche OPENAI_BASE_URL aktiv ist

  • welches OPENAI_IMAGE_MODEL konfiguriert ist

  • ob /models erreichbar ist

  • welche Modelle das Gateway meldet

  • ob das konfigurierte Modell in den /models-Ergebnissen erscheint

中文：如果你想做一次真实、计费的端到端探测，可以在调用 image_studio_doctor 时传 probe_generation=true。
English: Wenn Sie eine echte, kostenpflichtige End-to-End-Prüfung durchführen möchten, rufen Sie image_studio_doctor mit probe_generation=true auf.

Installation in Codex

Dieses Repo enthält bereits:

  • .codex-plugin/plugin.json

  • .mcp.json

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

Zur Installation in einem anderen Codex-Workspace:

  1. Kopieren Sie den Ordner image-studio-mcp in das plugins/-Verzeichnis des Ziel-Workspaces.

  2. Führen Sie npm install in diesem Plugin-Verzeichnis aus.

  3. Setzen Sie OPENAI_API_KEY in der lokalen MCP-Konfiguration.

  4. Passen Sie optional OPENAI_BASE_URL und OPENAI_IMAGE_MODEL an.

  5. Stellen Sie sicher, dass der Marketplace-Eintrag auf ./plugins/image-studio-mcp zeigt.

  6. Starten Sie Codex neu, falls das Plugin hinzugefügt wurde, während die App bereits geöffnet war.

Warum es möglicherweise nicht in den Codex MCP-Einstellungen erscheint

中文：Codex 里“设置 -> MCP 服务器”通常看的是全局 ~/.codex/config.toml 里的 [mcp_servers.*]，不一定会显示插件目录里的 .mcp.json。
English: In Codex beziehen sich „Einstellungen -> MCP-Server“ normalerweise auf globale [mcp_servers.*]-Einträge aus ~/.codex/config.toml, nicht unbedingt auf .mcp.json-Dateien im Plugin-Verzeichnis.

中文：所以“插件能加载”不等于“它会出现在全局 MCP 列表里”。
English: Das bedeutet, dass „Plugin installiert“ nicht immer dasselbe ist wie „in der globalen MCP-Einstellungsliste sichtbar“.

Installation in einem beliebigen MCP-Host

Jeder Host, der den Standard-MCP-stdio-Transport unterstützt, kann dieses Projekt verwenden.

Beispielkonfiguration:

{
  "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"
      }
    }
  }
}

Kopierbares Beispiel:

  • mcp.config.example.json

Minimale Nutzungsbeispiele

Offizielles OpenAI-kompatibles Beispiel

{
  "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"
}

Kompatibles Proxy-Beispiel

{
  "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"
}

Bearbeitungsbeispiel

{
  "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"
}

Verwendung in Codex

中文：

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

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

    • 生成什么

    • 输出到哪里

    • 要不要多张

    • 是生图还是改图

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

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

English:

  • Sie können einfach sagen: „Generiere ein Bild für mich“.

  • Es ist zuverlässiger, auch Folgendes anzugeben:

    • was generiert werden soll

    • wo es gespeichert werden soll

    • ob Sie mehrere Varianten wünschen

    • ob es sich um Text-zu-Bild oder Bildbearbeitung handelt

  • Wenn dies der erste Aufruf nach der Installation, nach dem Wechsel von Proxys oder nach einem zuvor fehlgeschlagenen Setup ist, führen Sie zuerst image_studio_doctor aus.

  • Wenn der Host nur den Skill-Text geladen, aber die tatsächlichen MCP-Tools nicht bereitgestellt hat, sollte das Modell dies klar kommunizieren, anstatt so zu tun, als ob die Bildgenerierung aufrufbar wäre.

Kontextgedächtnis in Codex

中文：

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

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

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

English:

  • Ja, aber hauptsächlich innerhalb des aktuellen Konversations-Threads, nicht als dauerhaftes Gedächtnis.

  • Nach einem neuen Thread, einer Kontextkomprimierung oder einem Neustart sind frühere Bildaufgaben-Details möglicherweise nicht mehr verfügbar.

  • Das sicherste Vorgehen ist, Ausgaben in einem klaren Pfad zu speichern und später erneut auf diesen Pfad zu verweisen.

Tools

image_studio_doctor

中文：做安装后自检、配置排查、代理排查。
English: Führt Selbsttests nach der Installation, Konfigurations- und Proxy-Fehlerbehebungen durch.

Wichtige Eingaben:

  • probe_generation

  • probe_prompt

  • models_preview_limit

generate_image

中文：根据提示词生成一张或多张图片。
English: Generiert ein oder mehrere Bilder aus einem Prompt.

Wichtige Eingaben:

  • prompt

  • output_dir

  • filename_prefix

  • count

  • size

  • quality

  • background

  • output_format

edit_image

中文：基于一张或多张已有图片进行改图。
English: Bearbeitet ein oder mehrere vorhandene Quellbilder basierend auf einem Prompt.

Wichtige Eingaben:

  • prompt

  • input_images

  • mask_image

  • output_dir

  • filename_prefix

  • count

  • size

  • quality

  • background

  • output_format

Fehlerbehebung

  • 401 invalid_api_key 中文：认证失败，通常是 key 不对、key 对这个代理不可用、或者上游没有授权。
    English: Authentifizierung fehlgeschlagen. Der Schlüssel ist falsch, für dieses Gateway nicht gültig oder es fehlt der Upstream-Zugriff.

  • 404 中文：路径大概率不对，常见原因是 OPENAI_BASE_URL 没写到 /v1。
    English: Wahrscheinlich ein Pfadproblem. Eine häufige Ursache ist, dass OPENAI_BASE_URL nicht auf /v1 endet.

  • 429 中文：代理或上游限流了。
    English: Der Proxy oder das Upstream-Konto ist ratenbegrenzt.

  • 524 中文：代理等上游太久超时了。
    English: Der Proxy hat zu lange auf den Upstream-Bildauftrag gewartet (Timeout).

  • No available compatible accounts 中文：代理当前没有可用的图像账号资源。
    English: Der Proxy hat derzeit keine verfügbaren Upstream-Bildkonten.

  • HTML instead of JSON 中文：通常说明 OPENAI_BASE_URL 指到了网页，不是 API。
    English: Bedeutet normalerweise, dass OPENAI_BASE_URL auf eine Dashboard-Seite zeigt, nicht auf einen API-Endpunkt.

Sicherheitshinweis

中文：不要把真实 key 提交进 Git，也不要到处手填进命令历史。优先通过 MCP 宿主的环境变量或本地私有配置注入。
English: Committen Sie keinen echten Schlüssel in Git und vermeiden Sie es, ihn in den Befehlsverlauf einzufügen. Bevorzugen Sie Umgebungsvariablen des MCP-Hosts oder eine private lokale Konfiguration.

Validierung

node --check ./scripts/openai-image-mcp.mjs
npm run validate
npm run doctor
npm run smoke:test

Skill-Validierung:

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observededit_image
    • First observedgenerate_image
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored across 2 tools

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

Related MCP Connectors