image2-tool

image2-tool is a cross-platform MCP server that adds real image generation and consecutive editing to Codex, Cursor, Claude, VS Code, and other MCP clients. It uses OpenAI's Image API or a compatible gateway such as Sub2API, saves full-resolution images locally, returns a small 384px preview, and lets later calls edit a prior result by persistent image_id.

It never installs a global skill. The installer changes only the selected MCP client config, keeps a backup, preserves unrelated JSON/TOML settings, and stores only an API-key environment-variable name or secret-file path—not the secret itself.

Compatibility

| Client target | Project config | Global/user config | | --- | --- | --- | | codex | .codex/config.toml | $CODEX_HOME/config.toml | | codex-app | Same Codex project config | Same Codex user config | | cursor | .cursor/mcp.json | ~/.cursor/mcp.json | | claude-code | .mcp.json | ~/.claude.json | | claude-desktop | N/A | Native Claude Desktop config path | | vscode | .vscode/mcp.json | Native VS Code user mcp.json path | | generic | .mcp.json | ~/.mcp.json, or --config PATH |

Supported operating systems:

• Windows: uses npx.cmd, %APPDATA% client paths, and Windows path syntax.
• macOS: supports Codex App/CLI and native Application Support paths.
• Linux: supports XDG config paths and both glibc/musl Sharp distributions supplied by npm.

Node.js 20 or newer is required. After installation, restart the desktop client or start a new task/session so it discovers the MCP server.

One-command setup

Mainland China (recommended):

npx -y --registry=https://registry.npmmirror.com image2-tool@latest setup

Official npm registry:

npx -y image2-tool@latest setup

That is the complete setup command. It securely prompts once for the Sub2API key with hidden input, stores it in the current user's private Codex credential directory, installs image2_tool into the global base Codex configuration, persists the registry used by npx, and makes the tool available to Codex App, Codex CLI, and every profile. Re-running the command reuses the existing credential file. Restart Codex App or start a new CLI task after setup.

Advanced options remain available, for example:

npx -y --registry=https://registry.npmmirror.com image2-tool@latest setup --client all

Manual installation

--api-key-env takes the name of an environment variable, not the key itself. Set that variable to the real key before installation. If it is missing or still contains a placeholder, the installer prints OS-specific remediation commands and the image tools refuse to send a request.

PowerShell (Windows):

$env:SUB2API_OPENAI_API_KEY = Read-Host "Paste your real Sub2API key"

Bash/zsh (macOS and Linux):

read -rsp "Paste your real Sub2API key: " SUB2API_OPENAI_API_KEY && export SUB2API_OPENAI_API_KEY && echo

Then install from the public npm registry:

npx -y image2-tool@latest install --client codex --scope global --base-url https://ai.tavonilo.com/v1 --api-key-env SUB2API_OPENAI_API_KEY

Mainland China npm mirror

The following command uses npmmirror for both the initial download and every later MCP launch. It does not change the user's global npm configuration:

npx -y --registry=https://registry.npmmirror.com image2-tool@latest install --client codex --scope global --base-url https://ai.tavonilo.com/v1 --api-key-env SUB2API_OPENAI_API_KEY --registry https://registry.npmmirror.com

The same line works in PowerShell, Command Prompt, Bash, and zsh. If a company mirror is used, replace both registry URLs. Run image2-tool doctor through the configured MCP client or with npx -y image2-tool@latest doctor to confirm api_key_ready: true without printing the secret.

From this repository checkout, the currently usable equivalent is:

npx -y ./tools/image2-tool install --client codex --scope project --base-url https://ai.tavonilo.com/v1 --api-key-env SUB2API_OPENAI_API_KEY --local

The install commands are intentionally one-line and work in Command Prompt, PowerShell, Bash, and zsh.

Codex App

Codex App and Codex CLI use the same MCP configuration. Project scope makes the tool available only to tasks opened in that repository:

npx -y image2-tool@latest install --client codex-app --scope global --base-url https://ai.tavonilo.com/v1 --api-key-env SUB2API_OPENAI_API_KEY

Global scope makes it available to every new Codex App/CLI task in the default configuration; no --profile launch flag is required. Use --scope project only when deliberate repository-level isolation is wanted. Codex v2 profile files currently ignore mcp_servers; --profile is retained only as an optional suggested launch label and never controls MCP isolation.

Several clients at once

Install project configs for Codex, Cursor, Claude Code, and VS Code:

npx -y image2-tool@latest install --client codex,cursor,claude-code,vscode --scope project --base-url https://ai.tavonilo.com/v1 --api-key-env SUB2API_OPENAI_API_KEY

--client all installs those clients and the OS-native global Claude Desktop config. Existing client configuration is merged and backed up before modification.

Claude Desktop and GUI authentication

GUI applications may not inherit variables exported by a terminal. A secret file is the portable alternative:

npx -y image2-tool@latest install --client claude-desktop --api-key-file /absolute/private/path/image-api.key --base-url https://api.openai.com/v1

Create that file yourself with only the API key, restrict it to the current user (chmod 600 on macOS/Linux or user-only ACLs on Windows), and never commit it. The installer records only its path. You may instead configure OPENAI_API_KEY or the selected --api-key-env in the desktop application's launch environment.

Custom or unsupported MCP client

Generate standard mcpServers JSON at an explicit path:

npx -y image2-tool@latest install --client generic --config /absolute/path/mcp.json --base-url https://api.openai.com/v1 --api-key-env OPENAI_API_KEY

Offline/tarball distribution

Build and share the package:

cd tools/image2-tool
npm install
npm test
npm pack

Install the copied tarball and keep that tarball as the MCP runtime source:

npx -y --package=/absolute/path/image2-tool-0.3.2.tgz image2-tool install --client codex --scope project --package /absolute/path/image2-tool-0.3.2.tgz --base-url https://ai.example.com/v1 --api-key-env IMAGE_API_KEY

Tools and workflow

The MCP namespace is image2_tool and exposes:

• generate_image: generate one or more images.
• edit_image: edit by image_id, local path, optional references, or mask.
• status: report non-secret runtime configuration.

Users do not need to name the MCP or any tool. Its server instructions and tool metadata route normal requests such as “生成一张产品图” to generate_image, and “把这张图的背景改成白色” to edit_image. No global skill or prompt injection is installed.

Generation and editing return:

• the full-resolution local path;
• a persistent image_id, usable after an MCP/client restart;
• a token-efficient JPEG preview, disableable with include_preview=false.

Example request:

Generate a blue ceramic cup with a yellow star. Inspect the preview, then use its image_id to change only the cup to red.

Configuration

| Installer option | MCP environment | Default | | --- | --- | --- | | --base-url | IMAGE2_API_BASE_URL | https://api.openai.com/v1 | | --api-key-env | IMAGE2_API_KEY_ENV | OPENAI_API_KEY | | --api-key-file | IMAGE2_API_KEY_FILE | unset | | --model | IMAGE2_MODEL | gpt-image-2 | | --output-dir | IMAGE2_OUTPUT_DIR | $CODEX_HOME/image2-tool/output | | --registry | npx launcher --registry | current npm registry |

For native transparent output, select a model/provider that supports it. gpt-image-2 does not currently accept background=transparent.

The key format is provider-specific, so the installer deliberately does not require an sk- prefix. It does reject missing values, whitespace, environment-variable names used as values, and common placeholders such as YOUR_API_KEY, sk-xxx, and replace-me. A provider can still reject a syntactically plausible key on the first request; that error includes the HTTP status and provider message.

Safe update and removal

Re-run installation to update only image2_tool. Existing config is backed up beside the original file with .image2-tool.bak appended.

npx -y image2-tool@latest uninstall --client codex,cursor,claude-code,vscode --scope project

Generated images and secret files are never deleted by uninstall.

Acknowledgements

The design was informed by the MIT-licensed shinpr/mcp-image. image2-tool is an independent implementation focused on multi-client installation, Codex App/CLI support, OpenAI-compatible base URLs, secret-name/file forwarding, persistent edits, and token-efficient previews.