openai-gpt-image-mcp

openai-gpt-image-mcp

---

一个用于调用 OpenAI 的 GPT-4o/gpt-image-1 图像生成与编辑 API 的模型上下文协议（MCP）工具服务。

• 使用 OpenAI 的最新模型，根据文本提示词生成图像。
• 编辑图像（局部重绘、扩图、合成），并支持高级提示词控制。
• 支持：Claude Desktop、Cursor、VSCode、Windsurf，以及任何兼容 MCP 的客户端。

---

✨ 功能

• create-image：根据提示词生成图像，并提供高级选项（尺寸、质量、背景等）。
• edit-image：使用提示词和可选蒙版编辑或扩展图像，支持文件路径和 base64 输入。
• 文件输出：将生成的图像直接保存到磁盘，或以 base64 形式接收。

---

🚀 安装

git clone https://github.com/SureScaleAI/openai-gpt-image-mcp.git
cd openai-gpt-image-mcp
yarn install
yarn build

---

🔑 配置

添加到 Claude Desktop 或 VSCode（包括 Cursor/Windsurf）的配置中：

{
  "mcpServers": {
    "openai-gpt-image-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

也支持 Azure 部署：

{
  "mcpServers": {
    "openai-gpt-image-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": { 
        "AZURE_OPENAI_API_KEY": "sk-...",
        "AZURE_OPENAI_ENDPOINT": "my.endpoint.com",
        "OPENAI_API_VERSION": "2024-12-01-preview"
      }
    }
  }
}

也支持提供环境文件：

{
  "mcpServers": {
    "openai-gpt-image-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js", "--env-file", "./deployment/.env"]
    }
  }
}

---

⚡ 高级用法

• 对于 create-image，将 n 设为最多一次生成 10 张图像。
• 对于 edit-image，提供蒙版图像（文件路径或 base64）来控制编辑区域。
• 使用 --env-file path/to/file/.env 提供环境文件。
• 查看 src/index.ts 了解所有选项。

---

🧑‍💻 开发

• TypeScript 源文件：src/index.ts
• 构建：yarn build
• 运行：node dist/index.js

---

📝 许可证

MIT

---

🩺 故障排除

• 确保你的 OPENAI_API_KEY 有效且具有图像 API 访问权限。
• 你必须拥有一个已验证的 OpenAI 组织。验证后，图像 API 访问权限可能需要 15–20 分钟才能激活。
• 文件路径必须是绝对路径。
  • Unix/macOS/Linux：以 / 开头（例如，/path/to/image.png）
  • Windows：盘符后接 :（例如，C:/path/to/image.png 或 C:\path\to\image.png）
• 对于文件输出，请确保目录可写。
• 如果看到有关文件类型的错误，请检查图像文件的扩展名和格式。

---

⚠️ 限制与大文件处理

• 1MB 载荷限制： MCP 客户端（包括 Claude Desktop）对工具响应设有严格的 1MB 限制。如果以 base64 格式返回，大型图片（尤其是高分辨率图片或多张图片）很容易超出此限制。
• 自动切换为文件输出： 如果图片总大小超过 1MB，工具会自动将图片保存到磁盘，并返回文件路径，而不是 base64。这样可确保兼容性，并避免出现 result exceeds maximum length of 1048576 之类的错误。
• 默认文件位置： 如果未指定 file_output 路径，图片将以唯一文件名保存到 /tmp（或 MCP_HF_WORK_DIR 环境变量设置的目录）。
• 环境变量：
  • MCP_HF_WORK_DIR：设置此变量以控制大型图片和文件输出的保存位置。示例：export MCP_HF_WORK_DIR=/your/desired/dir
• 最佳实践： 对于大型图片或生产环境中的图片，始终使用文件输出，并确保客户端已配置为处理文件路径。

---

📚 参考资料

• OpenAI 图片 API 文档

---

🙏 致谢

• 使用 @modelcontextprotocol/sdk 构建
• 使用 openai Node.js SDK
• 由 SureScale.ai 构建
• 感谢 Axle Research and Technology 的贡献