Gpt Image 1 MCP

🚀 @cloudwerxlab/gpt-image-1-mcp

这是一个基于OpenAI gpt-image-1 模型的模型上下文协议（MCP）服务器，可用于生成和编辑图像，为AI图像生成提供了便捷的工作流程。

🚀 快速开始

你可以直接使用NPX运行此MCP服务器，而无需进行安装。在npm上查看。

npx -y @cloudwerxlab/gpt-image-1-mcp

-y 标志会自动对安装过程中可能出现的任何提示回答“是”。

📋 前提条件

🔑 环境变量

💻 使用NPX的示例

Linux/macOS

# 设置你的OpenAI API密钥
export OPENAI_API_KEY=sk-your-openai-api-key

# 可选：设置自定义输出目录
export GPT_IMAGE_OUTPUT_DIR=/home/username/Pictures/ai-generated-images

# 使用NPX运行服务器
npx -y @cloudwerxlab/gpt-image-1-mcp

Windows (PowerShell)

# 设置你的OpenAI API密钥
$env:OPENAI_API_KEY = "sk-your-openai-api-key"

# 可选：设置自定义输出目录
$env:GPT_IMAGE_OUTPUT_DIR = "C:\Users\username\Pictures\ai-generated-images"

# 使用NPX运行服务器
npx -y @cloudwerxlab/gpt-image-1-mcp

Windows (Command Prompt)

:: 设置你的OpenAI API密钥
set OPENAI_API_KEY=sk-your-openai-api-key

:: 可选：设置自定义输出目录
set GPT_IMAGE_OUTPUT_DIR=C:\Users\username\Pictures\ai-generated-images

:: 使用NPX运行服务器
npx -y @cloudwerxlab/gpt-image-1-mcp

🔌 与MCP客户端集成

🛠️ 在MCP客户端中进行设置

步骤1：找到设置文件

• Roo：c:\Users\<username>\AppData\Roaming\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json
• VS Code MCP扩展：查看扩展文档以获取设置文件的位置
• Cursor：~/.config/cursor/mcp_settings.json (Linux/macOS) 或 %APPDATA%\Cursor\mcp_settings.json (Windows)
• Augment：~/.config/augment/mcp_settings.json (Linux/macOS) 或 %APPDATA%\Augment\mcp_settings.json (Windows)
• Windsurf：~/.config/windsurf/mcp_settings.json (Linux/macOS) 或 %APPDATA%\Windsurf\mcp_settings.json (Windows)

步骤2：添加配置

将以下配置添加到 mcpServers 对象中：

{
  "mcpServers": {
    "gpt-image-1": {
      "command": "npx",
      "args": [
        "-y",
        "@cloudwerxlab/gpt-image-1-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "PASTE YOUR OPEN-AI KEY HERE",
        "GPT_IMAGE_OUTPUT_DIR": "OPTIONAL: PATH TO SAVE GENERATED IMAGES"
      }
    }
  }
}

不同操作系统的示例配置

Windows

{
  "mcpServers": {
    "gpt-image-1": {
      "command": "npx",
      "args": ["-y", "@cloudwerxlab/gpt-image-1-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-your-openai-api-key",
        "GPT_IMAGE_OUTPUT_DIR": "C:\\Users\\username\\Pictures\\ai-generated-images"
      }
    }
  }
}

Linux/macOS

{
  "mcpServers": {
    "gpt-image-1": {
      "command": "npx",
      "args": ["-y", "@cloudwerxlab/gpt-image-1-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-your-openai-api-key",
        "GPT_IMAGE_OUTPUT_DIR": "/home/username/Pictures/ai-generated-images"
      }
    }
  }
}

注意：对于Windows路径，在JSON中使用双反斜杠 (\\) 来转义反斜杠字符。对于Linux/macOS，使用正斜杠 (/)。

✨ 主要特性

🎨 核心工具

• create_image：根据文本提示生成新图像。
• create_image_edit：使用文本提示和掩码编辑现有图像。

🚀 主要优势

• 与MCP客户端简单集成。
• 完全访问OpenAI的 gpt-image-1 功能。
• 简化AI图像生成的工作流程。

💡 增强功能

📊 输出与格式化

• ✅ 精美格式化输出：响应包含表情符号和详细信息。
• ✅ 自动保存图像：所有生成的图像都保存到磁盘，便于访问。
• ✅ 详细的令牌使用情况：查看每个请求的令牌消耗情况。

⚙️ 配置与处理

• ✅ 可配置的输出目录：自定义图像保存位置。
• ✅ 文件路径支持：使用文件路径而不是Base64编码来编辑图像。
• ✅ 全面的错误处理：详细的错误报告，包含特定的错误代码、描述和故障排除建议。

🔄 工作原理

🖼️ 图像生成

1. 服务器接收提示和参数。
2. 使用 gpt-image-1 模型调用OpenAI API。
3. API返回Base64编码的图像。
4. 服务器将图像保存到配置的目录。
5. 返回包含路径和元数据的格式化响应。

✏️ 图像编辑

1. 服务器接收图像、提示和可选的掩码。
2. 对于文件路径，读取并为API准备文件。
3. 使用直接的curl命令进行正确的MIME处理。
4. API返回Base64编码的编辑后图像。
5. 服务器将图像保存到配置的目录。
6. 返回包含路径和元数据的格式化响应。

📁 输出目录行为

📂 存储位置

• 🔹 默认位置：用户图片文件夹下的 gpt-image-1 子文件夹（例如，Windows上的 C:\Users\username\Pictures\gpt-image-1）。
• 🔹 自定义位置：通过 GPT_IMAGE_OUTPUT_DIR 环境变量设置。
• 🔹 备用位置：./generated-images（如果无法确定图片文件夹）。

🗂️ 文件管理

• 🔹 目录创建：如果输出目录不存在，将自动创建。
• 🔹 文件命名：图像以带时间戳的文件名保存（例如，image-2023-05-05T12-34-56-789Z.png）。
• 🔹 跨平台：在Windows、macOS和Linux上均可使用，并能正确检测图片文件夹。

📦 安装指南

NPM包

该包可在npm上获取：@cloudwerxlab/gpt-image-1-mcp

你可以全局安装它：

npm install -g @cloudwerxlab/gpt-image-1-mcp

或者如快速开始部分所示，直接使用npx运行它。

💻 使用示例

工具：create_image

根据文本提示生成新图像。

参数

示例

<use_mcp_tool>
<server_name>gpt-image-1</server_name>
<tool_name>create_image</tool_name>
<arguments>
{
  "prompt": "A futuristic city skyline at sunset, digital art",
  "size": "1024x1024",
  "quality": "high",
  "n": 1,
  "background": "auto"
}
</arguments>
</use_mcp_tool>

响应

该工具返回：

• 包含生成图像详细信息的格式化文本消息。
• 作为Base64编码数据的图像。
• 包括令牌使用情况和文件路径的元数据。

工具：create_image_edit

使用文本提示和可选的掩码编辑现有图像。

参数

使用Base64编码图像的示例

<use_mcp_tool>
<server_name>gpt-image-1</server_name>
<tool_name>create_image_edit</tool_name>
<arguments>
{
  "image": "BASE64_ENCODED_IMAGE_STRING",
  "prompt": "Add a small robot in the corner",
  "mask": "BASE64_ENCODED_MASK_STRING",
  "quality": "high"
}
</arguments>
</use_mcp_tool>

使用文件路径的示例

<use_mcp_tool>
<server_name>gpt-image-1</server_name>
<tool_name>create_image_edit</tool_name>
<arguments>
{
  "image": {
    "filePath": "C:/path/to/your/image.png"
  },
  "prompt": "Add a small robot in the corner",
  "mask": {
    "filePath": "C:/path/to/your/mask.png"
  },
  "quality": "high"
}
</arguments>
</use_mcp_tool>

响应

该工具返回：

• 包含编辑后图像详细信息的格式化文本消息。
• 作为Base64编码数据的编辑后图像。
• 包括令牌使用情况和文件路径的元数据。

🔧 故障排除

🚨 常见问题

🔍 错误处理和报告

MCP服务器包含全面的错误处理，当出现问题时提供详细信息。当发生错误时：

1. 错误格式：所有错误都返回以下内容：
   • 描述问题的清晰错误消息。
   • 特定的错误代码或类型。
   • 可用时提供有关错误的额外上下文。
2. AI助手行为：当与AI助手一起使用此MCP服务器时：
   • AI将始终报告完整的错误消息，以帮助进行故障排除。
   • AI将用通俗易懂的语言解释错误的可能原因。
   • AI将建议解决问题的具体步骤。

📄 许可证

本项目采用MIT许可证 - 有关详细信息，请参阅 LICENSE 文件。

许可证摘要

MIT许可证是一种宽松的许可证，简洁明了。它允许人们在适当归因且无担保的情况下对代码进行任何操作。

你可以自由地：

• 商业使用该软件。
• 修改该软件。
• 分发该软件。
• 私下使用和修改该软件。

在以下条件下：

• 在所有副本或实质性使用的作品中包含原始版权声明和许可证声明。

限制：

• 作者不提供软件的任何担保，也不对任何损害负责。

🙏 致谢

感谢以下方面的支持：

• OpenAI：提供 gpt-image-1 模型。
• model-context-protocol/mcp：提供协议规范。

如果你发现任何问题或有功能请求，请 报告错误 或 请求功能。访问 我们的网站 了解更多信息。

本项目由 CLOUDWERX 用心开发。