image-mcp

一个基于 MCP 的生图服务器，面向兼容 OpenAI Images API 的服务端实现。它提供一个 create-image 工具，可以按提示词生成图片，并支持两种输出方式：

直接保存到磁盘
以 base64 形式返回给 MCP 客户端

官方参考：

MCP TypeScript SDK 官方文档：https://ts.sdk.modelcontextprotocol.io/
MCP 官方 SDK 页面：https://modelcontextprotocol.io/docs/sdk
OpenAI 图片生成官方文档：https://developers.openai.com/api/docs/guides/image-generation

特性

提供 create-image MCP 工具
支持 prompt 生图
支持传入 model，默认值为 gpt-image-2
支持传入默认尺寸比例选项：1:1、9:16、16:9
支持传入 n 指定生成数量
支持输出到磁盘 file
支持以内联 base64 形式返回
支持配置上游图片服务 baseURL
支持自定义请求 headers
支持配置 API_KEY
支持配置默认生图模型
基于 stdio 运行，方便接入 Claude Desktop、Cursor、Cherry Studio 等 MCP 客户端

项目结构

.
├── .env.example
├── package.json
├── src
│   ├── config.ts
│   ├── image-api.ts
│   └── index.ts
└── README.md

环境要求

Node.js >= 18.17
一个兼容 OpenAI Images API 的图片生成服务

安装

npm install

配置

服务通过环境变量读取上游图片接口配置。

项目启动时会自动加载当前工作目录下的 .env 文件，因此本地开发时可以直接把配置写进 .env，无需先手动 export。

必填或常用配置

| 变量名 | 说明 | 默认值 | | -------------------------- | ----------------------------------------- | --------------------------- | | IMAGE_API_BASE_URL | 上游图片服务地址，通常为 https://xxx/v1 | https://api.openai.com/v1 | | IMAGE_API_KEY | 上游图片服务 API Key | 无 | | IMAGE_MODEL | 默认生图模型名 | gpt-image-2 | | IMAGE_API_HEADERS | 额外请求头，JSON 字符串格式 | {} | | IMAGE_OUTPUT_DIR | 默认落盘目录 | generated-images | | IMAGE_REQUEST_TIMEOUT_MS | 请求超时时间，单位毫秒 | 300000 |

兼容别名

为了方便迁移，也支持以下别名：

OPENAI_BASE_URL
OPENAI_API_KEY
OPENAI_IMAGE_MODEL
OPENAI_MODEL

配置示例

export IMAGE_API_BASE_URL="https://api.openai.com/v1"
export IMAGE_API_KEY="sk-xxxxx"
export IMAGE_MODEL="gpt-image-2"
export IMAGE_API_HEADERS='{"X-Request-Source":"image-mcp"}'
export IMAGE_OUTPUT_DIR="./generated-images"
export IMAGE_REQUEST_TIMEOUT_MS="300000"

也可以参考仓库中的 .env.example。

启动方式

开发模式

npm run dev

构建并运行

npm run build
npm start

MCP调试

npx @modelcontextprotocol/inspector node dist/index.js

MCP 工具说明

工具名

create-image

输入参数

| 参数名 | 类型 | 必填 | 说明 | | ---------------- | --------------------------- | ---- | --------------------------------------------------------- | | prompt | string | 是 | 生图提示词 | | model | string | 否 | 本次调用使用的模型名，不传则用 IMAGE_MODEL | | size | "1:1" \| "9:16" \| "16:9" | 否 | 默认尺寸比例选项，默认 1:1 | | customSize | string | 否 | 自定义原始像素尺寸，例如 1024x1024。传入后会覆盖 size | | n | number | 否 | 生成图片数量，默认 1 | | output | "file" \| "base64" | 否 | 输出模式，默认 file | | outputDir | string | 否 | 当 output=file 时使用的输出目录 | | fileNamePrefix | string | 否 | 当 output=file 时使用的文件名前缀 |

输出结果

尺寸会按以下默认映射传给上游图片接口：

| 比例选项 | 实际尺寸 | | -------- | ----------- | | 1:1 | 1024x1024 | | 9:16 | 1024x1792 | | 16:9 | 1792x1024 |

当 `output=file`

返回结构中会包含：

mode
model
size
count
createdAt
files

其中 files 形如：

[
  {
    "path": "/absolute/path/generated-images/cute-cat-1.png",
    "mimeType": "image/png"
  }
]

当 `output=base64`

返回结构中会包含：

mode
model
size
count
createdAt
images

其中 images 形如：

[
  {
    "base64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "mimeType": "image/png",
    "revisedPrompt": "..."
  }
]

原始 base64 会放在 structuredContent.images[].base64 中，便于客户端直接取用。

使用示例

示例 1：生成图片并保存到磁盘

{
  "prompt": "a cinematic close-up of a silver robot reading a newspaper in a rainy cafe",
  "model": "gpt-image-2",
  "size": "1:1",
  "n": 1,
  "output": "file",
  "outputDir": "./generated-images",
  "fileNamePrefix": "robot-cafe"
}

示例 2：生成图片并返回 base64

{
  "prompt": "minimalist poster design for a mountain travel campaign",
  "size": "9:16",
  "n": 2,
  "output": "base64"
}

MCP 客户端接入

下面给出一个通用的 stdio 配置示例。你可以按自己使用的 MCP 客户端格式做微调。

方式 1：开发模式运行

{
  "mcpServers": {
    "image-mcp": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/Users/xiaobc/work/projects/xiaobc/image-mcp",
      "env": {
        "IMAGE_API_BASE_URL": "https://api.openai.com/v1",
        "IMAGE_API_KEY": "sk-xxxxx",
        "IMAGE_MODEL": "gpt-image-2",
        "IMAGE_API_HEADERS": "{\"X-Request-Source\":\"image-mcp\"}",
        "IMAGE_OUTPUT_DIR": "./generated-images"
      }
    }
  }
}

方式 2：构建后运行

{
  "mcpServers": {
    "image-mcp": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/Users/xiaobc/work/projects/xiaobc/image-mcp",
      "env": {
        "IMAGE_API_BASE_URL": "https://api.openai.com/v1",
        "IMAGE_API_KEY": "sk-xxxxx",
        "IMAGE_MODEL": "gpt-image-2"
      }
    }
  }
}

实现说明

服务通过 stdio 暴露 MCP 能力
工具调用上游接口地址为：{IMAGE_API_BASE_URL}/images/generations
size 默认提供 1:1 / 9:16 / 16:9 三个比例选项
默认比例会分别映射到 1024x1024 / 1024x1792 / 1792x1024
如果传入 customSize，会优先使用该值
默认会发送 Authorization: Bearer <IMAGE_API_KEY>
如果配置了 IMAGE_API_HEADERS，会把这些自定义请求头一并带上
自定义请求头会覆盖默认同名请求头，方便接入非标准兼容服务
如果上游返回的是图片 URL，服务会自动下载并转成 base64，再决定是落盘还是返回给客户端
如果上游较慢，可以通过 IMAGE_REQUEST_TIMEOUT_MS 调大超时时间

常见问题

1. 为什么明明配置了 API Key 还是鉴权失败？

可能原因：

上游服务要求的认证头不是 Authorization
你的网关要求额外的自定义头

这种场景下可以通过 IMAGE_API_HEADERS 覆盖或补充请求头，例如：

export IMAGE_API_HEADERS='{"Authorization":"Bearer xxx","X-App-Id":"demo"}'

2. 为什么返回的不是 png？

服务会根据上游返回的 MIME 类型或图片内容自动判断扩展名，可能保存为：

.png
.jpg
.webp

3. base64 太大怎么办？

如果图片较大或生成数量较多，建议使用 output=file，这样更适合日常工作流，也能避免 MCP 响应体过大。

后续可扩展方向

增加图片编辑 edit-image
增加参考图输入
增加输出格式、质量、背景透明等高级参数
增加 HTTP Streamable MCP 传输方式

MCP Servers

image-mcp

特性

项目结构

环境要求

安装

配置

必填或常用配置

兼容别名

配置示例

启动方式

开发模式

构建并运行

MCP调试

MCP 工具说明

工具名

输入参数

输出结果

当 `output=file`

当 `output=base64`

使用示例

示例 1：生成图片并保存到磁盘

示例 2：生成图片并返回 base64

MCP 客户端接入

方式 1：开发模式运行

方式 2：构建后运行

实现说明

常见问题

1. 为什么明明配置了 API Key 还是鉴权失败？

2. 为什么返回的不是 png？

3. base64 太大怎么办？

后续可扩展方向

Install Package (if required)

Cursor configuration (mcp.json)

image-mcp

特性

项目结构

环境要求

安装

配置

必填或常用配置

兼容别名

配置示例

启动方式

开发模式

构建并运行

MCP调试

MCP 工具说明

工具名

输入参数

输出结果

当 output=file

当 output=base64

使用示例

示例 1：生成图片并保存到磁盘

示例 2：生成图片并返回 base64

MCP 客户端接入

方式 1：开发模式运行

方式 2：构建后运行

实现说明

常见问题

1. 为什么明明配置了 API Key 还是鉴权失败？

2. 为什么返回的不是 png？

3. base64 太大怎么办？

后续可扩展方向

Install Package (if required)

Cursor configuration (mcp.json)

当 `output=file`

当 `output=base64`