ChatGPT Image Bridge

ChatGPT Image Bridge gives text-only agents a portable image workflow:

1. Generate or edit a raster with the user's signed-in Codex and ChatGPT account.

2. Save it directly to <project>/assets/generated/ when the caller supplies project_root.

3. Inspect, compare, transcribe, or critique it through a separate OpenAI vision turn.

4. Return the vision findings as plain text that any primary model can use.

The repository is an Agent Plugins 1.0 package. Its actual tool boundary is standard MCP, so it is not tied to Factory, DeepSeek Harness, Codex, Cursor, VS Code, or another individual host.

What it exposes

• imagegen_status: verify the local Codex login, image entitlement, and vision model.

• generate_image: generate an image and optionally save it in an active project.

• generate_image_edit: edit one to four local or data-URL references.

• get_image_job: recover a generation that outlives the host's normal MCP timeout.

• analyze_image: turn a generated job, local image path, or data URL into model-readable visual evidence.

Successful jobs always retain a canonical copy in the plugin data directory. Supplying an absolute project_root additionally writes a uniquely named, non-overwriting copy to assets/generated/.

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

Requirements

• macOS, Linux, or Windows with Python 3.11 or newer.

• uv on PATH for the portable plugin launcher.

• A locally installed Codex executable. The macOS ChatGPT bundle is detected automatically; elsewhere, put codex on PATH or set CODEX_BIN.

• A ChatGPT account signed into Codex with image generation and a model that advertises image input.

The bridge deliberately removes API-key environment variables from the Codex child process. It is designed to use the user's local ChatGPT/Codex login, not silently spend an API key.

Each installation uses the recipient's own local Codex login and account entitlement. The plugin never bundles or transfers the publisher's login, subscription, cookies, or tokens.

Run locally

uv sync
uv run chatgpt-image-bridge-mcp --stdio

For the MCP Inspector:

uv run mcp dev src/chatgpt_image_bridge_mcp/server.py

For a localhost-only Streamable HTTP endpoint:

uv run chatgpt-image-bridge-mcp --http --port 8788

The endpoint is http://127.0.0.1:8788/mcp. HTTP mode has no portable authentication in this alpha release and only accepts loopback bindings. Use stdio for normal installations. A future authenticated network deployment should be a separate, explicitly reviewed feature.

Install as an Agent Plugin

The portable package entry points are:

• plugin.json

• mcp.json

• skills/chatgpt-image-workflow/SKILL.md

Load the repository directory in any Agent Plugins 1.0 client. The client supplies PLUGIN_ROOT and a writable PLUGIN_DATA; mcp.json launches the server with uv over stdio.

Agent Plugins standardizes the package, not a universal install command. Until clients converge on distribution UX, Git remains the most reliable source of truth.

Hosts that expose a separate built-in image tool may choose that tool by name before consulting MCP. If the built-in tool is subscription-gated, explicitly select this plugin's generate_image tool or its server namespace. See client notes.

Build the OpenAI/Codex compatibility package

OpenAI's current plugin directory uses a separate .codex-plugin/plugin.json package shape. Generate a self-contained compatibility artifact from the same source rather than maintaining a second server implementation:

python3 scripts/build_openai_plugin.py

The result is dist/openai/chatgpt-image-bridge-mcp/. It contains the same server and workflow skill, plus OpenAI's .codex-plugin/plugin.json and .mcp.json manifests. Keeping this as generated output avoids behavioral drift between the cross-vendor package and the OpenAI-specific install artifact.

The builder copies an explicit release allowlist only and rejects symbolic links, Python bytecode, or the local checkout path. This makes the compatibility artifact reproducible from a clean Git checkout and prevents ignored developer files from leaking into a release.

Configure as plain MCP

Clients that support MCP but not Agent Plugins can launch the same server directly. Adapt the outer configuration shape to the host:

{
  "command": "uv",
  "args": [
    "run",
    "--project",
    "/absolute/path/to/chatgpt-image-bridge-mcp",
    "--locked",
    "--no-dev",
    "chatgpt-image-bridge-mcp",
    "--stdio"
  ],
  "env": {
    "CHATGPT_IMAGE_BRIDGE_MCP_DATA_DIR": "/absolute/writable/path/chatgpt-image-bridge-mcp",
    "UV_PROJECT_ENVIRONMENT": "/absolute/writable/path/chatgpt-image-bridge-mcp/venv"
  }
}

Intended model workflow

For generation:

1. Call imagegen_status once.

2. Call generate_image with the visual prompt and the active project's absolute root.

3. Use the returned relative_saved_path in the website or application.

4. If the task requires visual judgment, call analyze_image with the returned job_id.

5. Continue using the written analysis as visual evidence. Do not replace the raster with SVG or CSS merely because the primary model is text-only.

For an existing image, call analyze_image with exactly one source: job_id, image_paths, or image_data_urls.

Configuration

By default, local path access follows MCP's trusted-stdio model: a caller may name any path the account owner can read, while generated project copies are limited to assets/generated/. For shared or less-trusted harnesses, set CHATGPT_IMAGE_BRIDGE_MCP_ALLOWED_ROOTS to one or more approved project directories.

The Codex child receives a minimal operating environment rather than inheriting the host process environment. Do not add secrets to CHATGPT_IMAGE_BRIDGE_MCP_CODEX_ENV_ALLOWLIST.

Development

uv sync
uv run ruff check src tests scripts
uv run pytest
uv build
python3 scripts/build_openai_plugin.py

The tests use a fake account runtime and make no provider calls or paid image requests. A separate live smoke test is required to prove a particular Codex build and account entitlement.

Before publishing a release, run the commands above from a clean checkout and verify one real generation plus one analyze_image follow-up using the packaged plugin in at least one MCP host. Runtime compatibility can change independently of this repository because the Codex app-server bridge is experimental.

License

MIT. See LICENSE.