image2-mcp

image2-mcp

本地 stdio MCP 服务，用于通过 OpenAI-compatible /v1/images/generations 接口生成图片并保存到本地文件。适合 Claude Code、Claude Desktop 以及使用 new-api 中转站的用户。

功能

• 提供一个 MCP 工具：generate_image
• 支持可配置 image2 接口地址、API Key、模型名
• 支持 gpt-image-2 文档尺寸，最长边可达 3840px
• 支持 n=1-10 批量生成
• 支持 b64_json 和 url 两种上游返回格式
• 图片保存到本地，只向 Claude 返回路径和元数据，不返回大体积 base64
• 默认避免覆盖已有文件

环境变量

变量	必填	默认值	说明
IMAGE2_API_BASE_URL	是	-	可填完整 /v1/images/generations 端点，也可填基础 URL
IMAGE2_API_KEY	是	-	用户自己的 API Key
IMAGE2_MODEL	否	gpt-image-2	图片生成模型名
IMAGE2_OUTPUT_DIR	否	outputs/images	默认输出目录
IMAGE2_DEFAULT_SIZE	否	1024x1024	默认尺寸
IMAGE2_DEFAULT_QUALITY	否	standard	默认质量

推荐尺寸：

• 1024x1024
• 1792x1024
• 2048x2048
• 3840x2160

兼容旧尺寸：

• auto
• 1024x1536
• 1536x1024

推荐质量：

• standard
• medium
• hd

兼容旧质量：

• auto -> standard
• low -> standard
• high -> hd

本地开发

npm install
npm run build

开发运行：

IMAGE2_API_BASE_URL="https://your-newapi.example.com/v1/images/generations" \
IMAGE2_API_KEY="sk-xxx" \
npm run dev

Claude Code 配置示例

发布到 npm 后：

{
  "mcpServers": {
    "image2": {
      "command": "npx",
      "args": ["-y", "image2-mcp"],
      "env": {
        "IMAGE2_API_BASE_URL": "https://your-newapi.example.com/v1/images/generations",
        "IMAGE2_API_KEY": "sk-xxx",
        "IMAGE2_MODEL": "gpt-image-2",
        "IMAGE2_OUTPUT_DIR": "outputs/images"
      }
    }
  }
}

本地源码调试：

{
  "mcpServers": {
    "image2": {
      "command": "node",
      "args": ["/absolute/path/to/tools/image2-mcp/dist/index.js"],
      "env": {
        "IMAGE2_API_BASE_URL": "https://your-newapi.example.com/v1/images/generations",
        "IMAGE2_API_KEY": "sk-xxx"
      }
    }
  }
}

Claude Desktop 配置示例

在 claude_desktop_config.json 中加入：

{
  "mcpServers": {
    "image2": {
      "command": "npx",
      "args": ["-y", "image2-mcp"],
      "env": {
        "IMAGE2_API_BASE_URL": "https://your-newapi.example.com/v1/images/generations",
        "IMAGE2_API_KEY": "sk-xxx"
      }
    }
  }
}

工具参数

generate_image：

{
  "prompt": "一张赛博朋克风格的无人机海报",
  "size": "3840x2160",
  "quality": "hd",
  "n": 1,
  "background": "auto",
  "style": "cinematic, high detail",
  "outputPath": "outputs/images/poster.png"
}

参数说明：

参数	必填	说明
prompt	是	图片描述
size	否	图片尺寸，推荐 1024x1024 / 1792x1024 / 2048x2048 / 3840x2160
quality	否	standard / medium / hd
n	否	生成数量，范围 1-10，默认 1
outputPath	否	输出文件或目录；n > 1 时会自动追加编号
style	否	附加到 prompt 的风格描述
background	否	auto / transparent / opaque，仅在上游支持时有效

4K 示例

{
  "prompt": "未来城市夜景，霓虹灯，雨夜，电影级构图",
  "size": "3840x2160",
  "quality": "hd",
  "n": 1,
  "outputPath": "outputs/images/future-city-4k.png"
}

批量生成示例

{
  "prompt": "白色背景上的蓝色圆形图标，极简矢量风格",
  "size": "1024x1024",
  "quality": "standard",
  "n": 3,
  "outputPath": "outputs/images/blue-circle.png"
}

会生成类似：

outputs/images/blue-circle-1.png
outputs/images/blue-circle-2.png
outputs/images/blue-circle-3.png

返回内容包含：

• 本地图片路径列表
• 文件大小
• 模型名
• 尺寸
• 质量
• 图片序号
• 上游返回的 revised prompt（如果有）

超时建议

4K 图片生成可能耗时较长。Claude Code 中可按需提高：

export MCP_TOOL_TIMEOUT=300000

如果上游返回 504 Gateway Timeout，建议继续提高客户端或网关超时时间。

注意事项

• 本服务只做图片生成，不包含 OCR 或图片理解。
• 不建议让工具返回 base64 图片正文，容易超过 MCP 输出限制。
• 如果 IMAGE2_API_BASE_URL 只填写基础 URL，服务会自动拼接 /v1/images/generations。
• 如果指定输出文件已存在，服务会自动追加序号，避免覆盖。
• 4K 尺寸是否可用以你的上游渠道实际支持为准；如果渠道不支持，通常会返回 Invalid size。