MCP Servers

模型上下文协议服务器、框架、SDK 和模板的综合目录。

I
Image MCP
作者 @xiaobc1234
GitHub 仓库(1 星标)

支持符合openai格式的生图mcp服务

创建于 4/22/2026
更新于 about 4 hours ago
README
View Source
Repository documentation and setup instructions

image-mcp

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

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

官方参考：

特性

  • 提供 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 传输方式
快速设置
此服务器的安装指南

安装包 （如果需要）

npx @modelcontextprotocol/server-image-mcp

Cursor 配置 (mcp.json)

{ "mcpServers": { "xiaobc1234-image-mcp": { "command": "npx", "args": [ "xiaobc1234-image-mcp" ] } } }