ImageForge MCP

English | 中文

A lightweight TypeScript MCP server for generating and editing images with OpenAI gpt-image-2, and for text-to-image generation with Zhipu BigModel image models.

• OpenAI text-to-image requests use POST /v1/images/generations; Zhipu uses POST /api/paas/v4/images/generations.

• OpenAI image editing and reference-image generation use multipart POST /v1/images/edits.

• Generated images are returned as native MCP image content blocks and can optionally be saved locally.

Features

• OpenAI model: gpt-image-2

• Zhipu models: glm-image, cogview-4-250304, cogview-4, cogview-3-flash

• MCP tools: generate_image and edit_image

• Text-to-image generation

• Image generation guided by one or more reference images

• Zhipu text-to-image generation with optional server-side watermark control

• Editing one or more existing images

• Local absolute paths and HTTP(S) URLs as image inputs

• PNG, JPEG, and WebP input and output

• Up to 16 input images, with a 50 MB limit per image and a 200 MB combined limit

• Optional local output path with automatic parent-directory creation

• URL validation against non-public network targets, with DNS addresses pinned to the actual connection

• Bounded input loading concurrency

• stdio transport

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

Provider capability matrix

Zhipu BigModel support

ImageForge calls the official Zhipu image generation endpoint with Bearer authentication. The supported models and ImageForge behavior are:

quality: "auto" is an ImageForge compatibility value: it omits the quality field and lets Zhipu apply the model default. ImageForge validates only the WIDTHxHEIGHT shape of size; Zhipu remains authoritative for each model's supported dimensions and pixel limits. The MCP-level default remains 1024x1024 for compatibility across providers.

Zhipu returns one temporary image URL. ImageForge downloads it immediately and returns native MCP image content after validating the actual PNG, JPEG, or WebP signature. The download always enforces public-address checks, DNS pinning, redirect revalidation, a 30-second timeout, and a 50 MB limit, even when IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS is enabled for user-supplied OpenAI input images. Provider credentials are never forwarded to the image URL.

watermark_enabled follows these rules:

• Omitted: ImageForge does not send the field, so the Zhipu account/model default applies.

• true: requests Zhipu's explicit and implicit watermarks.

• false: requests Zhipu to disable watermarks; the account must have the required watermark-removal authorization. ImageForge never removes or edits a watermark locally.

• OpenAI: the same unified parameter is silently ignored.

See the official Zhipu image generation API for current provider-side size, quality, watermark, and account-policy rules.

OpenAI-compatible CPA and gateway support

ImageForge MCP works with OpenAI and with CPA, relay, or proxy services that implement a compatible OpenAI Images API. This includes deployments based on projects such as New API, CLI Proxy API, and similar OpenAI-compatible gateways.

Compatibility depends on the gateway implementation rather than its product name:

• Text-to-image requires POST /v1/images/generations.

• Reference-image generation and editing require multipart POST /v1/images/edits with image[] file forwarding.

• Responses must include Base64 image data in data[0].b64_json.

• The configured model name must accept gpt-image-2.

A gateway that only implements /v1/images/generations can be used for text-to-image generation, but not for reference-image generation or editing.

Requirements

• Node.js 22 or later

• An OpenAI API key or a compatible gateway token; a Zhipu API key is needed only when using the zhipu provider

Install and build

npm install
npm run build

MCP client configuration

For production use, start the published npm package with npx. No repository clone or local build is required. Inject credentials through the MCP client environment:

{
  "mcpServers": {
    "imageforge": {
      "command": "npx",
      "args": ["-y", "imageforge-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-token",
        "OPENAI_IMAGE_MODEL": "gpt-image-2",
        "IMAGEFORGE_PROVIDER": "openai",
        "IMAGEFORGE_INPUT_CONCURRENCY": "4"
      }
    }
  }
}

-y allows npx to download or update the package without an interactive install prompt. Pin a specific version when reproducible deployments are required, for example "imageforge-mcp@0.4.0".

For a Zhipu-default MCP server, use an independent credential and provider configuration:

{
  "mcpServers": {
    "imageforge-zhipu": {
      "command": "npx",
      "args": ["-y", "imageforge-mcp@0.4.0"],
      "env": {
        "IMAGEFORGE_PROVIDER": "zhipu",
        "ZHIPU_API_KEY": "your-zhipu-token",
        "ZHIPU_IMAGE_MODEL": "glm-image"
      }
    }
  }
}

ZHIPU_BASE_URL is optional and defaults to https://open.bigmodel.cn/api/paas/v4. ZHIPU_IMAGE_MODEL is optional and defaults to glm-image. Zhipu credentials never fall back to OpenAI variables, and OpenAI credentials never fall back to Zhipu variables. A per-call provider, api_key, base_url, or model overrides the corresponding environment configuration.

OPENAI_BASE_URL is optional. When it is unset, ImageForge MCP uses the official OpenAI endpoint https://api.openai.com/v1. Set it only when using New API, CLI Proxy API, or another OpenAI-compatible gateway:

"OPENAI_BASE_URL": "https://your-openai-compatible-gateway.example/v1"

The value must point to the gateway's /v1 root. ImageForge MCP appends /images/generations or /images/edits as required.

IMAGEFORGE_INPUT_CONCURRENCY optionally controls how many local or remote input images are loaded at once. It defaults to 4, must be a positive integer, and is capped at the per-call limit of 16 input images. The combined input size remains capped at 200 MB.

DNS safety checks are enabled by default. Set IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS=true only when private-network or DNS-proxy image URLs must be supported. This disables non-public address rejection and DNS pinning for every redirect hop, which can expose the MCP process to SSRF. HTTP(S)-only URLs, the credential restriction, redirect limit, size limits, and image signature validation remain enforced. Accepted true values are true, 1, yes, and on; false values are false, 0, no, and off.

Do not commit real API keys to Git or write them into shared configuration files.

Codex local development configuration

Create a project-scoped .codex/config.toml using paths that match your machine:

[mcp_servers.imageforge_dev]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/ImageForgeMCP/dist/index.js"]
cwd = "/absolute/path/to/ImageForgeMCP"
env_vars = ["OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_IMAGE_MODEL", "ZHIPU_API_KEY", "ZHIPU_BASE_URL", "ZHIPU_IMAGE_MODEL", "IMAGEFORGE_PROVIDER", "IMAGEFORGE_INPUT_CONCURRENCY", "IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS"]
startup_timeout_sec = 10
tool_timeout_sec = 300
enabled = true
required = false

Export the environment variables before starting Codex:

export OPENAI_API_KEY="your-gateway-token"
export OPENAI_BASE_URL="https://your-openai-compatible-gateway.example/v1"
export OPENAI_IMAGE_MODEL="gpt-image-2"
export IMAGEFORGE_INPUT_CONCURRENCY="4"

cd /absolute/path/to/ImageForgeMCP
codex app

For a Zhipu-default development process, export the Zhipu variables instead of the OpenAI credential/model variables:

export IMAGEFORGE_PROVIDER="zhipu"
export ZHIPU_API_KEY="your-zhipu-token"
export ZHIPU_IMAGE_MODEL="glm-image"
# Optional: export ZHIPU_BASE_URL="https://open.bigmodel.cn/api/paas/v4"

Codex loads project-scoped .codex/config.toml only for trusted projects. After adding or changing the MCP configuration, restart Codex or open a new task, then use /mcp verbose to confirm that imageforge_dev exposes:

• generate_image

• edit_image

After changing the TypeScript source, rebuild dist/index.js and restart the task using the MCP server:

npm run build

See the official Codex MCP documentation for all configuration options.

generate_image

Without reference_images, the tool uses /images/generations. With OpenAI reference images, it uploads them as multipart image[] files to /images/edits.

Zhipu supports synchronous text-to-image only. It rejects reference_images before reading the referenced files or making a request, does not support edit_image, and ignores output_format. No Authorization header is sent to the image CDN, and the returned MCP MIME type is based on the downloaded image bytes.

Zhipu glm-image without an explicit quality or watermark override:

{
  "provider": "zhipu",
  "model": "glm-image",
  "prompt": "A hand-painted lakeside village at sunrise, warm light, no text",
  "size": "1280x1280",
  "quality": "auto"
}

Zhipu glm-image requesting no provider watermark:

{
  "provider": "zhipu",
  "model": "glm-image",
  "prompt": "A clean studio product render on a neutral background, no text",
  "size": "1280x1280",
  "quality": "hd",
  "watermark_enabled": false,
  "output_path": "outputs/zhipu-product.png"
}

Faster CogView request using provider-standard quality:

{
  "provider": "zhipu",
  "model": "cogview-4",
  "prompt": "A colorful editorial illustration of a modern city park, no text",
  "size": "1024x1024",
  "quality": "standard"
}

Common Zhipu failures are returned as tool errors with the HTTP status and a provider response excerpt of at most 500 characters. Authentication failures must be fixed rather than retried; HTTP 429 with business code 1113 means the account balance is insufficient, while other 429 codes can indicate rate, model-load, or account-plan limits. ImageForge does not automatically retry paid generation requests. See the official Zhipu error-code reference for current business-code meanings.

edit_image

edit_image uses the same model, API, output, and local-save parameters as generate_image, but requires input_images:

Local images are read directly. URL images are downloaded and validated before upload. Every redirect target is revalidated, non-public addresses are rejected, and the validated DNS results are pinned to the actual connection to prevent DNS rebinding between validation and download.

Configuration precedence is: tool arguments, environment variables, then built-in defaults.

When output_path is supplied, ImageForge MCP returns the native MCP image content block, saves the decoded image, and includes the final absolute path in a text content block. Missing parent directories are created automatically. Existing files are not overwritten.

Some OpenAI-compatible gateways may return dimensions different from the requested size; the actual returned file dimensions are authoritative.

Verification

npm test
npm run check

Tests use a local HTTP mock. They do not call a real image API or incur generation charges.

License

MIT

中文说明

ImageForge MCP 是一个轻量的 TypeScript MCP 图片生成与编辑服务，支持通过 OpenAI Images API 调用 gpt-image-2，并支持通过智谱 BigModel API 进行文生图。

• OpenAI 纯文本生图调用 POST /v1/images/generations；智谱调用 POST /api/paas/v4/images/generations。

• OpenAI 图片编辑和参考图生图调用 multipart POST /v1/images/edits。

• 生成结果以原生 MCP image 内容块返回，也可以同时保存到本地。

功能

• OpenAI 模型：gpt-image-2

• 智谱模型：glm-image、cogview-4-250304、cogview-4、cogview-3-flash

• MCP 工具：generate_image、edit_image

• 支持纯文本生图

• 支持一张或多张参考图引导生图

• 支持一张或多张图片编辑

• 输入图片支持本地绝对路径和 HTTP(S) URL

• 输入与输出支持 PNG、JPEG、WebP

• 最多 16 张输入图片，每张不超过 50 MB，单次调用合计不超过 200 MB

• 支持通过 output_path 保存到本地，并自动创建父目录

• URL 安全校验，拒绝非公网地址，并将校验后的 DNS 地址固定到实际连接

• 输入图片加载并发受控

• stdio Transport

供应商能力矩阵

智谱 BigModel 支持

ImageForge 使用 Bearer 认证调用智谱官方图片生成接口，各模型在当前实现中的规则如下：

quality: "auto" 是 ImageForge 的兼容值，表示不向智谱发送 quality，由智谱使用对应模型的默认质量。ImageForge 对 size 只校验 宽x高 格式，具体尺寸、整除要求和像素上限以智谱接口为准；为了保持供应商间兼容，MCP 层默认尺寸仍为 1024x1024。

智谱返回一张图片的临时 URL，ImageForge 会立即下载，并在验证实际内容为 PNG、JPEG 或 WebP 后返回原生 MCP 图片内容。即使用户为了 OpenAI 输入图设置了 IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS，智谱结果图下载仍强制执行公网地址检查、DNS 固定、重定向复核、30 秒超时和 50 MB 限制，且不会把供应商认证信息转发给图片地址。

watermark_enabled 规则：

• 不传：ImageForge 不发送该字段，使用智谱账号或模型默认行为。

• true：请求智谱添加显式水印和隐式数字水印。

• false：请求智谱关闭水印，账号必须具备相应去水印权限；ImageForge 不会在本地擦除或修改水印。

• OpenAI：统一参数会被静默忽略。

智谱服务端当前尺寸、质量、水印和账号政策应以官方图片生成 API 文档为准。

OpenAI 兼容 CPA 与网关

ImageForge MCP 不仅支持 OpenAI 官方接口，也支持实现了 OpenAI Images API 兼容协议的 CPA、中转或代理服务，包括基于 New API、CLI Proxy API 等项目部署的 OpenAI 兼容网关。

是否兼容取决于网关实现的接口能力，而不是产品名称：

• 纯文本生图需要实现 POST /v1/images/generations。

• 参考图生图和图片编辑需要实现 multipart POST /v1/images/edits，并正确转发 image[] 文件。

• 响应需要在 data[0].b64_json 中返回 Base64 图片数据。

• 网关需要接受 gpt-image-2 模型名。

如果网关只实现了 /v1/images/generations，仍可用于纯文本生图，但不能使用参考图生图和图片编辑。

环境要求

• Node.js 22 或更高版本

• OpenAI API Key，或 OpenAI 兼容 CPA/网关签发的令牌

安装与构建

npm install
npm run build

MCP 客户端配置

生产环境推荐直接通过 npx 启动 npm 官方包，无需克隆仓库或在本地构建。通过 MCP 客户端环境变量注入密钥：

{
  "mcpServers": {
    "imageforge": {
      "command": "npx",
      "args": ["-y", "imageforge-mcp"],
      "env": {
        "OPENAI_API_KEY": "你的令牌",
        "OPENAI_IMAGE_MODEL": "gpt-image-2",
        "IMAGEFORGE_PROVIDER": "openai",
        "IMAGEFORGE_INPUT_CONCURRENCY": "4"
      }
    }
  }
}

-y 允许 npx 在没有交互式安装提示的情况下下载或更新包。如果部署需要固定版本，可将包名写成 "imageforge-mcp@0.4.0"。

如果希望 MCP 默认使用智谱，应使用独立的智谱凭据与供应商配置：

{
  "mcpServers": {
    "imageforge-zhipu": {
      "command": "npx",
      "args": ["-y", "imageforge-mcp@0.4.0"],
      "env": {
        "IMAGEFORGE_PROVIDER": "zhipu",
        "ZHIPU_API_KEY": "你的智谱令牌",
        "ZHIPU_IMAGE_MODEL": "glm-image"
      }
    }
  }
}

ZHIPU_BASE_URL 可选，默认值为 https://open.bigmodel.cn/api/paas/v4；ZHIPU_IMAGE_MODEL 可选，默认值为 glm-image。智谱与 OpenAI 的环境密钥不会互相回退。单次调用传入的 provider、api_key、base_url 或 model 优先于对应环境变量。

OPENAI_BASE_URL 是可选配置。不设置时，ImageForge MCP 默认使用 OpenAI 官方接口 https://api.openai.com/v1。只有使用 New API、CLI Proxy API 或其他 OpenAI 兼容网关时才需要设置：

"OPENAI_BASE_URL": "https://你的-OpenAI-兼容网关域名/v1"

地址应填写到网关的 /v1 根路径为止，服务会根据请求追加 /images/generations 或 /images/edits。

IMAGEFORGE_INPUT_CONCURRENCY 可选，用于控制同时加载的本地或远程输入图片数量。默认值为 4，必须是正整数，并直接受单次最多 16 张输入图片的限制。单次调用的输入图片合计大小仍固定限制为 200 MB。

DNS 安全检查默认启用。只有确实需要访问私有网络地址或 DNS 代理生成的图片地址时，才应设置 IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS=true。启用后，每次重定向都不再执行非公网地址拦截和 DNS 地址固定，可能使 MCP 进程面临 SSRF 风险。HTTP(S) 协议限制、URL 凭据限制、重定向次数、图片大小和图片魔数校验仍然有效。真值支持 true、1、yes、on，假值支持 false、0、no、off。

不要把真实 API Key 写入 Git 或其他共享配置文件。

Codex 本地开发配置

根据本机路径创建项目级 .codex/config.toml：

[mcp_servers.imageforge_dev]
command = "/你的/node/绝对路径"
args = ["/你的/ImageForgeMCP/绝对路径/dist/index.js"]
cwd = "/你的/ImageForgeMCP/绝对路径"
env_vars = ["OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_IMAGE_MODEL", "ZHIPU_API_KEY", "ZHIPU_BASE_URL", "ZHIPU_IMAGE_MODEL", "IMAGEFORGE_PROVIDER", "IMAGEFORGE_INPUT_CONCURRENCY", "IMAGEFORGE_SKIP_DNS_SAFETY_CHECKS"]
startup_timeout_sec = 10
tool_timeout_sec = 300
enabled = true
required = false

启动 Codex 前设置环境变量：

export OPENAI_API_KEY="你的网关令牌"
export OPENAI_BASE_URL="https://你的-OpenAI-兼容网关域名/v1"
export OPENAI_IMAGE_MODEL="gpt-image-2"
export IMAGEFORGE_INPUT_CONCURRENCY="4"

cd /你的/ImageForgeMCP/绝对路径
codex app

如果本地开发进程默认使用智谱，应改为导出智谱配置，不要复用 OpenAI 密钥或模型变量：

export IMAGEFORGE_PROVIDER="zhipu"
export ZHIPU_API_KEY="你的智谱令牌"
export ZHIPU_IMAGE_MODEL="glm-image"
# 可选：export ZHIPU_BASE_URL="https://open.bigmodel.cn/api/paas/v4"

Codex 只会加载已信任项目中的 .codex/config.toml。新增或修改 MCP 配置后，需要重新启动 Codex 或新建任务，再使用 /mcp verbose 确认 imageforge_dev 提供以下工具：

• generate_image

• edit_image

修改 TypeScript 源码后，需要重新构建并重启使用该 MCP 的任务：

npm run build

完整配置说明见 Codex MCP 官方文档。

generate_image

不传 reference_images 时调用 /images/generations；OpenAI 传入参考图时，将图片作为 multipart image[] 文件上传到 /images/edits。

智谱首版仅支持同步文生图，不支持参考图和 edit_image。传入 reference_images 时会在读取参考文件和发起请求前明确报错；output_format 对智谱不生效。下载图片时不携带 Authorization，最终 MCP MIME 类型以实际图片内容为准。

智谱 glm-image，不覆盖供应商默认质量和水印行为：

{
  "provider": "zhipu",
  "model": "glm-image",
  "prompt": "日出时分的手绘湖畔村庄，暖色光线，无文字",
  "size": "1280x1280",
  "quality": "auto"
}

智谱 glm-image 请求关闭供应商水印：

{
  "provider": "zhipu",
  "model": "glm-image",
  "prompt": "中性背景上的干净棚拍产品渲染，无文字",
  "size": "1280x1280",
  "quality": "hd",
  "watermark_enabled": false,
  "output_path": "outputs/zhipu-product.png"
}

CogView 使用供应商标准质量快速生成：

{
  "provider": "zhipu",
  "model": "cogview-4",
  "prompt": "色彩丰富的现代城市公园编辑插画，无文字",
  "size": "1024x1024",
  "quality": "standard"
}

智谱失败会作为 MCP 工具错误返回，包含 HTTP 状态和最多 500 个字符的供应商错误摘要。认证失败必须修正配置而不是重试；HTTP 429 且业务错误码为 1113 表示账户欠费，其他 429 错误也可能表示限流、模型繁忙或套餐限制。ImageForge 不会自动重试可能产生费用的生图请求。业务错误码的当前含义以智谱官方错误码文档为准。

edit_image

edit_image 与 generate_image 使用相同的模型、API、输出和本地保存参数，但 input_images 必填：

本地图片会直接读取；URL 图片会经过下载和安全校验后再上传。每次重定向都会重新校验目标地址，非公网地址会被拒绝，同时会将校验后的 DNS 结果固定到实际连接，防止校验与下载之间发生 DNS Rebinding。

配置优先级为：工具参数、环境变量、内置默认值。

传入 output_path 时，服务会在返回原生 MCP 图片内容块的同时保存文件，并在文本内容块中返回最终绝对路径。父目录不存在时会自动创建；已有文件不会被覆盖。

部分 OpenAI 兼容网关可能不会严格遵循请求中的 size，应以实际返回文件的尺寸为准。

验证

npm test
npm run check

测试使用本地 HTTP mock，不会调用真实图片 API，也不会产生生图费用。

许可证

MIT