Skip to main content
Glama
deeneszh
PEKI7483

GPT Image Playground MCP

by PEKI7483
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

GPT Image Playground MCP

让 Agent 通过浏览器使用 GPT Image Playground，完成图片生成、状态查询和原图保存。

你不需要修改 Playground 源码，也不需要把 Playground 的 API Key 交给 MCP。桥接服务只负责传递任务，浏览器扩展只操作页面中可见的控件。

NOTE

本项目适合已经可以正常打开 GPT Image Playground 的浏览器用户。图片页面仍由 Playground 负责登录、生成和管理自己的会话。

能做什么

  • 根据提示词生成图片；

  • 查询生成任务的状态；

  • 将已完成任务的原图保存到指定位置；

  • 让多个 Agent 共用同一个浏览器任务队列；

  • 通过 MCP 参数传入参考图。

MCP 工具为 generate_image、get_task_status 和 download_image。

Related MCP server: openai-gpt-image-1-mcp

工作方式

Agent
  -> MCP stdio
  -> 127.0.0.1 本机桥接服务
  -> Chromium 扩展
  -> GPT Image Playground 页面
  -> 返回任务结果

任务会按照提交顺序逐个处理。生成时间由 Playground 决定，没有固定的 20 秒完成期限；扩展领取任务后会持续等待页面完成，不会因为等待时间较长而重复提交。

开始之前

请准备：

  • Node.js 18 或更高版本；

  • Chrome、Chromium 或其他支持 Manifest V3 的 Chromium 浏览器；

  • 一个可以正常打开 GPT Image Playground 的页面；

  • 一个支持 MCP 的 Agent 客户端。

安装

1. 获取项目并构建

git clone https://github.com/PEKI7483/image-playground-mcp.git
cd image-playground-mcp
npm install
npm run build

2. 自动配置 Agent

先进行只读检查。它会识别常见 Agent 的配置位置，不会修改任何文件：

npx -y github:PEKI7483/image-playground-mcp setup --check

只配置一个 Agent：

npx -y github:PEKI7483/image-playground-mcp setup --agent codex

为已经检测到配置文件的 Agent 一次性写入：

npx -y github:PEKI7483/image-playground-mcp setup --all

安装器会在修改已有配置前自动创建备份，并保留其他 MCP 服务。它写入的是跨平台的 npx 启动方式，不会把连接 Token 写进 Agent 配置。

支持的目标包括：

codex、claude-code、gemini、cursor、cline、roo、windsurf 和 claude-desktop。

预览即将发生的修改：

npx -y github:PEKI7483/image-playground-mcp setup --agent codex --dry-run

如需使用其他端口，可以在配置时指定：

npx -y github:PEKI7483/image-playground-mcp setup --agent codex --port 8790

端口修改后，扩展设置中的图片工具地址也要使用同一个端口。

3. 安装浏览器扩展

  1. 打开 Chrome 或 Chromium，访问 chrome://extensions。

  2. 开启“开发者模式”。

  3. 选择“加载已解压的扩展程序”。

  4. 选择本项目中的 extension 目录。

  5. 打开 GPT Image Playground 的普通画廊页面，并保持页面打开。

  6. 启动或重启 Agent 客户端。

  7. 点击浏览器工具栏中的扩展图标，查看运行概览。

通常不需要填写任何 Token。扩展会在启动后自动请求本机 Bridge 的 /auth 端点，并完成连接。只有在你主动修改过桥接端口时，才需要在“连接设置”中更新图片工具地址。

手动添加方式

自动配置适合大多数用户。若你希望由 Agent 的命令行工具直接添加 MCP，可以使用以下命令。

Codex CLI 和 Codex 应用

codex mcp add gpt-image-playground -- \
  npx -y github:PEKI7483/image-playground-mcp

检查结果：

codex mcp list

更多信息请参阅 Codex MCP 文档。

Claude Code

claude mcp add --transport stdio gpt-image-playground -- \
  npx -y github:PEKI7483/image-playground-mcp

Gemini CLI、Cursor、Cline、Roo Code、Windsurf 和 Claude Desktop

在客户端的 MCP 设置中添加一个本地 STDIO 服务，或将以下对象合并到已有的 mcpServers 配置中：

{
  "gpt-image-playground": {
    "command": "npx",
    "args": ["-y", "github:PEKI7483/image-playground-mcp"]
  }
}

请保留已有的其他 MCP 服务。Windows 用户通常由安装器自动使用 npx.cmd；手动编辑配置时，以客户端文档要求的命令格式为准。

保存后，请重启客户端或重新加载 MCP 配置。

确认连接

  1. 打开 GPT Image Playground 的普通画廊模式页面。

  2. 确认提示词输入框和生成按钮可见。

  3. 确认 Agent 已加载 gpt-image-playground MCP。

  4. 打开扩展小窗口，查看“运行概览”。

正常状态应包括：桥接服务可访问、扩展已连接、已找到图片页面。运行概览会显示当前队列和正在处理的任务。

桥接服务只监听本机回环地址。可以使用下面的命令确认本机端口已经启动；命令不会输出 Token：

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8787/auth

返回 200 表示 Bridge 已提供自动配对入口。

调用示例

生成图片

调用 generate_image 时至少传入一个提示词：

{
  "prompt": "一座临海的现代图书馆，清晨柔和的自然光，建筑摄影风格"
}

工具会等待页面完成，不会把 20 秒当作任务期限。多个 Agent 同时提交时，请等待队列处理，不要重复提交同一请求。

使用参考图

参考图可以通过 MCP 参数传入：

{
  "prompt": "保留参考图的构图，改成水彩插画",
  "reference_image_paths": [
    "<absolute-path-to-reference-image>"
  ]
}

支持 PNG、JPEG/JPG、WebP、GIF 和 AVIF；最多 16 张，单张不超过 8 MiB，总大小不超过 24 MiB。MCP 服务会读取文件并交给页面原有的多文件上传控件，图片处理仍由 Playground 完成。

下载原图

generate_image 返回 task_id 后，可以调用 download_image：

{
  "task_id": "上一步返回的 task_id",
  "output_path": "<absolute-path-to-output-image>",
  "image_index": 0
}

下载读取的是任务详情中的原图，而不是任务卡片缩略图。详情原图可能晚于任务状态加载；扩展会兼容普通 img 元素，最多等待 60 秒，并在完成或失败后关闭详情弹窗。

已有输出文件只有在内容完全相同时才会幂等成功；内容不同则会提示冲突，不会覆盖原文件。

自动认证说明

扩展和 MCP 进程之间仍然有一层本机连接保护，但普通用户不需要手动处理它：

  1. Bridge 启动时生成本机 Token；

  2. 扩展请求 http://127.0.0.1:<端口>/auth；

  3. 扩展将 Token 保存在扩展的会话存储中，并用于后续请求；

  4. MCP 进程也会自动发现同一个 Bridge 的 Token。

/auth 是唯一免认证的本机配对入口，其他 /v1/* 接口仍然需要连接保护。Token 不写入 Cookie、网页 localStorage 或 Agent 配置，也不是 Playground API Key。

由于 /auth 面向本机自动配对，本机上拥有运行权限的其他进程理论上也可以请求它。这是降低配置成本与加强本机进程隔离之间的明确取舍。Bridge 默认只监听 127.0.0.1，不会对局域网开放。

安全与隐私

IMPORTANT

Playground 的登录状态和 API Key 由 Playground 自己管理。本项目不读取或保存 Cookie、网页localStorage、IndexedDB、页面 JavaScript 变量，也不直接调用图片 API。

  • 扩展只操作 Playground 页面中可见的 DOM 控件；

  • Bridge 只监听本机回环地址；

  • 多个 Agent 可以共用同一个 Bridge 和队列；

  • 任务始终由 Bridge 串行分配给浏览器扩展；

  • 如果你需要进程级别的更强身份隔离，可以改用固定 Token 或 Native Messaging 部署方式。

常见问题

扩展显示“图片工具没有回应”

请依次确认：

  1. Agent 客户端已经启动并加载 MCP；

  2. 扩展中的地址是 http://127.0.0.1:8787，或与你配置的端口一致；

  3. chrome://extensions 中的扩展已经重新加载；

  4. GPT Image Playground 的普通画廊页面仍处于打开状态。

修改端口后，请同时更新安装器配置和扩展中的图片工具地址。通常不需要清理或复制任何 Token。

图片页面数量为 0

请打开普通画廊模式，并确认提示词输入框可见。扩展不会通过直接调用图片 API 工作，也不会处理没有对应页面控件的页面。

图片生成时间较长

不同提示词、参考图和页面状态所需时间可能不同。请查看 Playground 任务卡片和扩展运行概览，不要重复点击生成。已领取的任务会持续等待页面完成。

参考图没有出现

请确认文件路径是绝对路径、格式受支持、文件大小符合限制，并且 Playground 页面存在多文件上传控件。

下载原图失败

请确认任务已经完成、任务卡片仍然可见，并使用新的输出路径。下载流程不会读取浏览器存储作为备用来源。

配置项

环境变量

默认值

说明

MCP_BRIDGE_PORT

8787

本机 Bridge 端口；扩展地址需要与它一致

MCP_BRIDGE_TOKEN

自动生成

高级部署可指定固定本机连接值；普通安装无需设置

MCP_ACTIVE_STALE_MS

0

可选的任务心跳失联处理；不会自动重复生成

通常不需要手动启动 Bridge。MCP 客户端启动服务时，会自动发现或启动本机 Bridge。直接运行 npm run bridge 主要用于诊断。

设计边界

  • 本项目不修改 GPT Image Playground 源码；

  • API Key 留在 Playground 自己的浏览器会话中；

  • 图片生成只通过页面可见操作完成；

  • 浏览器关闭后，页面任务无法继续执行；

  • 多个 Agent 共享同一个串行任务队列。

反馈与帮助

欢迎提交 Issue。为了帮助我们更快定位问题，请提供 Agent 客户端及版本、浏览器及版本、扩展运行概览状态和任务错误信息。分享日志前，请移除 Token、个人路径和其他敏感信息。

感谢你花时间尝试这个工具。希望它能让图片生成工作更顺手，也让 Agent 与 Playground 之间的协作更自然。

Available Tools

3 tools
download_imageB

把已完成任务中的图片从 Playground 页面保存到 MCP 主机的本地绝对路径。

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idYes
image_indexNo
output_pathYes

TDQS

B3.3/5.0
Behavior2/5

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

No annotations are provided, so the description must disclose behavioral traits. It only states the action (saving a file) without mentioning side effects, overwriting behavior, permission requirements, or error handling. The agent has no information about what happens if the task is incomplete or if the output path already exists.

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 concise sentence with no unnecessary words. It front-loads the key action and scope, making it easy to scan.

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 tool's complexity (3 parameters, no output schema, no annotations), the description is too minimal. It lacks essential context for parameter usage, expected behavior on failure, and any safety considerations, making it incomplete for an agent to confidently invoke the tool.

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

Parameters1/5

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

Schema coverage is 0% and the description does not explain any of the three parameters (task_id, image_index, output_path). The agent must infer meaning solely from parameter names, which is insufficient, especially for optional image_index which could be ambiguous.

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

Purpose5/5

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

The description clearly states the tool's purpose: downloading an image from a completed task to a local absolute path. It uses a specific verb (save/download) and resource (image from completed task), distinguishing it from sibling tools like generate_image and get_task_status.

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

Usage Guidelines4/5

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

The description explicitly mentions the precondition that the task must be completed, giving clear context for when to use this tool. However, it does not mention alternatives or when not to use it, though the distinct purpose makes the use case clear.

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

generate_imageA

通过已打开的 GPT Image Playground 页面生成图片，可先注入本地参考图。请求会被浏览器桥接扩展串行处理，直到页面报告完成或失败；没有 20 秒固定上限。

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes
reference_image_pathsNo

TDQS

A3.7/5.0
Behavior4/5

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

没有注解，描述承担了行为披露的全部责任。描述说明了请求会被串行处理、等待页面完成报告、没有20秒超时限制，这些是有用的行为细节，让代理了解执行模型。但未涉及权限、副作用或错误处理等，考虑到无注解，整体披露较充分。

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

Conciseness4/5

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

描述简洁，两个句子传达了核心功能和行为特征，没有冗余信息。第二句补充了重要的执行细节（串行处理、无固定超时），结构合理，但可再稍微结构化一点。

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

Completeness3/5

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

工具接受2个参数，无输出schema，描述提供了行为的额外细节（串行处理、异步等待）。但对于兄弟工具（get_task_status、download_image）的关系没有提及，缺少集成上下文的说明。考虑到相对简单，描述基本够用，但可以更全面。

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覆盖率为0%，描述仅提到了'注入本地参考图'对应reference_images参数，但核心参数prompt没有额外解释，仅从字段名推断其含义。描述未能完全补偿schema参数的缺乏，特别是prompt的格式、要求或约束未提及。

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

Purpose5/5

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

描述明确说明了工具的动作是生成图片，资源是GPT Image Playground页面，并提到可注入本地参考图。与兄弟工具get_task_status和download_image在功能上明显区分，目的清晰具体。

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?

描述暗示了使用场景（需要通过已打开的页面生成图片），但没有明确说明何时应使用此工具而非其他兄弟工具，也未提及限制条件（如页面必须已打开、注入参考图的步骤等）。缺少明确的'何时使用/何时不使用'指导。

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

get_task_statusB

查询 Playground 页面中某个生成任务的状态。

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idYes

TDQS

B3.3/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. It only states that the tool queries a status, implying a read-only operation, but it does not disclose return format, error behavior, or any Playground-specific constraints or side effects.

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?

One short sentence with no filler, directly stating the tool's purpose. It is front-loaded and appropriately sized for a simple status-query tool.

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?

The tool has one parameter and no output schema, yet the description does not explain what the status response looks like or how it relates to the sibling generate/download workflow. This leaves the agent with gaps in knowing how to interpret the result or integrate the tool.

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%, and the description does not explain the task_id parameter. While '某个生成任务' hints at the parameter's purpose, the description adds no concrete meaning beyond the schema's bare field name and type.

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

Purpose5/5

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

The description uses the specific verb '查询' (query) and a clear resource '生成任务的状态' (status of a generation task), scoped to the Playground page. This distinguishes it from sibling tools that generate or download images.

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 usage context is implied by the nature of the tool—checking status after generation—but there is no explicit guidance on when to use it vs. alternatives, no exclusions, and no mention of prerequisites.

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. 3 tool updatesv0.1.0
    • First observeddownload_image
    • First observedgenerate_image
    • First observedget_task_status
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

A3.8/5.0

Scored across 3 tools

Disambiguation5/5

Each tool handles a distinct phase of the image generation workflow: generating, checking status, and downloading. There is no overlap in their purposes, making it clear which tool to use at each step.

Naming Consistency5/5

All three tool names follow a consistent verb_noun pattern (generate_image, get_task_status, download_image), using snake_case and clear action-first naming. The pattern is uniform across the set.

Tool Count5/5

With only 3 tools, the server is tightly scoped to a single workflow (generate, track, download). This is appropriate for a focused purpose and each tool is necessary for the complete flow.

Completeness4/5

The workflow covers the essential lifecycle: generation initiation, status polling, and downloading results. A minor gap is the lack of a cancellation or listing tool, but agents can work around this by waiting or using status checks.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers