内容
# openai-gpt-image-mcp
<p align="center">
<a href="https://www.npmjs.com/package/@modelcontextprotocol/sdk"><img src="https://img.shields.io/npm/v/@modelcontextprotocol/sdk?label=MCP%20SDK&color=blue" alt="MCP SDK"></a>
<a href="https://www.npmjs.com/package/openai"><img src="https://img.shields.io/npm/v/openai?label=OpenAI%20SDK&color=blueviolet" alt="OpenAI SDK"></a>
<a href="https://github.com/SureScaleAI/openai-gpt-image-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/SureScaleAI/openai-gpt-image-mcp?color=brightgreen" alt="License"></a>
<a href="https://github.com/SureScaleAI/openai-gpt-image-mcp/stargazers"><img src="https://img.shields.io/github/stars/SureScaleAI/openai-gpt-image-mcp?style=social" alt="GitHub stars"></a>
<a href="https://github.com/SureScaleAI/openai-gpt-image-mcp/actions"><img src="https://img.shields.io/github/actions/workflow/status/SureScaleAI/openai-gpt-image-mcp/main.yml?label=build&logo=github" alt="Build Status"></a>
</p>
---
模型上下文协议（MCP）工具服务器，用于 OpenAI 的 GPT-4o/gpt-image-1 图片生成和编辑 API。
- **根据文本提示生成图片**，使用 OpenAI 的最新模型。
- **编辑图片**（修复、扩展、合成），具有高级提示控制。
- **支持**：Claude Desktop、Cursor、VSCode、Windsurf 以及任何兼容 MCP 的客户端。
---
## ✨ 功能
- **创建图片**：根据提示生成图片，具备高级选项（尺寸、质量、背景等）。
- **编辑图片**：使用提示和可选掩码编辑或扩展图片，支持文件路径和 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": ["/绝对路径/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 组织](https://platform.openai.com/account/organization)。验证后，可能需要 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 文档](https://platform.openai.com/docs/api-reference/images)
---
## 🙏 致谢
- 使用 [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) 构建
- 使用 [openai](https://www.npmjs.com/package/openai) Node.js SDK
- 由 [SureScale.ai](https://surescale.ai) 构建
