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 格式接收。

🚀 安装

sh
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）配置中添加：

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

⚡ 高级功能

• 对于 create-image，设置 n 可以一次生成最多 10 张图像。
• 对于 edit-image，提供一个掩码图像（文件路径或 base64）来控制编辑应用的位置。
• 查看 src/index.ts 获取所有选项。

🧑‍💻 开发

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

📝 许可证

MIT

🩺 故障排除

• 确保您的 OPENAI_API_KEY 是有效的，并且具有图像 API 访问权限。
• 您必须拥有一个已验证的 OpenAI 组织。验证后，可能需要 15-20 分钟才能激活图像 API 访问权限。
• 文件路径必须是绝对路径。
• 对于文件输出，请确保目录是可写的。
• 如果遇到有关文件类型的错误，请检查图像文件的扩展名和格式。

⚠️ 限制与大文件处理

• 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 构建