@shadowdqj/image-mcp

v0.1.0

Published

2 months ago

MCP server for OpenAI-compatible image generation and image editing APIs.

0High
0Medium
0Low

shadowdqj

mcp model-context-protocol openai image-generation image-editing

@shadowdqj/image-mcp

一个基于 stdio transport 的图片 MCP Server，面向 OpenAI-compatible Images API，支持文生图、图片编辑和蒙版局部编辑。

功能特性

generate_image：根据提示词生成图片。
edit_image：基于一张或多张本地图片进行编辑。
mask_edit_image：基于原图和蒙版进行局部重绘 / inpainting。
支持 OpenAI 或兼容 OpenAI Images API 的服务。
支持从环境变量读取 API Key、Base URL、模型名和输出目录。
支持 API 返回 b64_json 或图片 url。
自动把生成结果保存到本地文件，并在 MCP 工具结果中返回图片路径。
支持 extra_params 透传兼容服务的额外参数。

安装

全局安装：

npm install -g @shadowdqj/image-mcp

或者通过 npx 直接运行：

npx @shadowdqj/image-mcp

本地开发使用：

npm install
npm run build
npm run dev

环境变量

| 变量 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | | IMAGE_API_KEY | 是 | - | 图片 API Key，会作为 Authorization: Bearer ... 发送。 | | IMAGE_BASE_URL | 否 | https://api.openai.com/v1 | OpenAI-compatible API 根地址。 | | IMAGE_GENERATE_MODEL | 否 | gpt-image-1 | generate_image 默认使用的模型。 | | IMAGE_EDIT_MODEL | 否 | gpt-image-1 | edit_image 和 mask_edit_image 默认使用的模型。 | | IMAGE_OUTPUT_DIR | 否 | images | 图片输出目录，默认相对于 MCP 进程工作目录。 |

输出目录优先级：

工具参数 output_dir > 环境变量 IMAGE_OUTPUT_DIR > 默认 ./images

如果 MCP 客户端在某个项目工作区内启动该服务，默认会写入该工作区下的 images 目录。

MCP 客户端配置

使用 npx

适合不想全局安装的场景：

{
  "mcpServers": {
    "image-mcp": {
      "command": "npx",
      "args": ["@shadowdqj/image-mcp"],
      "env": {
        "IMAGE_API_KEY": "你的 API Key",
        "IMAGE_BASE_URL": "https://api.openai.com/v1",
        "IMAGE_GENERATE_MODEL": "gpt-image-1",
        "IMAGE_EDIT_MODEL": "gpt-image-1",
        "IMAGE_OUTPUT_DIR": "./images"
      }
    }
  }
}

使用全局命令

如果已经执行过 npm install -g @shadowdqj/image-mcp，可以这样配置：

{
  "mcpServers": {
    "image-mcp": {
      "command": "image-mcp",
      "env": {
        "IMAGE_API_KEY": "你的 API Key",
        "IMAGE_BASE_URL": "https://api.openai.com/v1",
        "IMAGE_OUTPUT_DIR": "./images"
      }
    }
  }
}

使用本地源码运行

在开发或调试当前仓库时，可以直接指向构建后的入口文件：

{
  "mcpServers": {
    "image-mcp": {
      "command": "node",
      "args": ["D:/Work/mcp/image-mcp/dist/index.js"],
      "env": {
        "IMAGE_API_KEY": "你的 API Key",
        "IMAGE_BASE_URL": "https://api.openai.com/v1",
        "IMAGE_OUTPUT_DIR": "./images"
      }
    }
  }
}

修改源码后需要先执行 npm run build，再让 MCP 客户端重新加载服务。

MCP 工具说明

generate_image

文生图工具，调用：

POST /images/generations

示例参数：

{
  "prompt": "一只陶瓷狐狸茶壶，放在阳光照进来的厨房桌面上",
  "size": "1024x1024",
  "n": 1,
  "quality": "high",
  "output_format": "png"
}

常用参数：

| 参数 | 必填 | 说明 | | --- | --- | --- | | prompt | 是 | 图片生成提示词。 | | model | 否 | 覆盖 IMAGE_GENERATE_MODEL。 | | size | 否 | 图片尺寸，例如 1024x1024。 | | n | 否 | 生成图片数量，范围 1-10。 | | quality | 否 | 图片质量，例如 low、medium、high、auto。 | | background | 否 | 背景选项，例如 transparent、opaque。 | | output_format | 否 | 输出格式，例如 png、jpeg、webp。 | | output_compression | 否 | 压缩比例，范围 0-100。 | | output_dir | 否 | 覆盖图片保存目录。 | | extra_params | 否 | 额外 JSON 字段，会合并到请求体。 |

返回结果示例：

{
  "images": [
    {
      "path": "D:\\your-workspace\\images\\2026-07-17T09-00-00-000Z-uuid.png"
    }
  ],
  "raw_count": 1
}

edit_image

图片编辑工具，调用：

POST /images/edits

单图编辑示例：

{
  "prompt": "把杯子改成蓝色，保持背景不变",
  "image_path": "./input.png",
  "size": "1024x1024",
  "output_format": "png"
}

多图编辑示例：

{
  "prompt": "把这些产品参考图合成为一张干净的广告图",
  "image_paths": ["./a.png", "./b.png"],
  "image_field": "image[]",
  "size": "1024x1024"
}

常用参数：

| 参数 | 必填 | 说明 | | --- | --- | --- | | prompt | 是 | 图片编辑提示词。 | | image_path | 否 | 单张输入图片路径。 | | image_paths | 否 | 多张输入图片路径。image_path 和 image_paths 至少提供一个。 | | image_field | 否 | multipart 图片字段名。单图默认 image，多图默认 image[]。 | | model | 否 | 覆盖 IMAGE_EDIT_MODEL。 | | size | 否 | 图片尺寸，例如 1024x1024。 | | n | 否 | 返回图片数量，范围 1-10。 | | output_format | 否 | 输出格式，例如 png、jpeg、webp。 | | output_dir | 否 | 覆盖图片保存目录。 | | extra_params | 否 | 额外 multipart 字段。对象类型会以 JSON 字符串发送。 |

mask_edit_image

蒙版编辑工具，适合局部重绘 / inpainting，调用：

POST /images/edits

示例参数：

{
  "prompt": "把蒙版区域替换成一束野花",
  "image_path": "./input.png",
  "mask_path": "./mask.png",
  "size": "1024x1024",
  "output_format": "png"
}

常用参数：

| 参数 | 必填 | 说明 | | --- | --- | --- | | prompt | 是 | 蒙版编辑提示词。 | | image_path | 否 | 输入原图路径。 | | image_paths | 否 | 多张输入图片路径。通常蒙版编辑只需要一张原图。 | | mask_path | 是 | 蒙版图片路径，会作为 multipart 字段 mask 上传。 | | image_field | 否 | 原图 multipart 字段名，默认 image。 | | model | 否 | 覆盖 IMAGE_EDIT_MODEL。 | | size | 否 | 图片尺寸，例如 1024x1024。 | | n | 否 | 返回图片数量，范围 1-10。 | | output_format | 否 | 输出格式，例如 png、jpeg、webp。 | | output_dir | 否 | 覆盖图片保存目录。 | | extra_params | 否 | 额外 multipart 字段。 |

与 OpenAI-compatible 服务对接

默认请求地址为：

https://api.openai.com/v1/images/generations
https://api.openai.com/v1/images/edits

如果使用其他兼容服务，只需要设置：

IMAGE_BASE_URL=https://your-provider.example.com/v1
IMAGE_API_KEY=your-provider-key

如果兼容服务的参数名和 OpenAI 略有不同，可以通过：

extra_params 透传额外字段。
image_field 调整图片 multipart 字段名。
model 在单次调用中覆盖默认模型。

返回结果与文件保存

工具不会把图片二进制直接塞进 MCP 响应，而是保存到本地并返回路径。

如果 API 返回：

b64_json：直接解码并保存到本地。
url：尝试下载 URL 并保存到本地；如果下载失败，会返回 URL 和 warning。

文件名格式类似：

2026-07-17T09-00-00-000Z-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png

发布

发布前先构建并检查打包内容：

npm run build
npm pack --dry-run

发布到 npm：

npm publish --access public

package.json 已配置：

{
  "publishConfig": {
    "access": "public"
  }
}

注意事项

IMAGE_API_KEY 是必填项，未配置时调用工具会报错。
默认输出目录是 MCP 进程当前工作目录下的 images。
如果 MCP 客户端不是从你的项目目录启动服务，建议显式设置 IMAGE_OUTPUT_DIR。
edit_image 和 mask_edit_image 需要传入本地图片路径，路径需要对 MCP 服务进程可读。
当前项目没有内置 .env 文件读取，推荐通过 MCP 客户端的 env 配置传入环境变量。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@shadowdqj/image-mcp

功能特性

安装

环境变量

MCP 客户端配置

使用 npx

使用全局命令

使用本地源码运行

MCP 工具说明

generate_image

edit_image

mask_edit_image

与 OpenAI-compatible 服务对接

返回结果与文件保存

发布

注意事项