shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

gpt-image-1-mcp

一个基于OpenAI gpt-image-1模型的图像生成与编辑MCP服务器，支持通过文本提示创建和修改图像，提供便捷的集成方式和丰富的配置选项。

article

README

🚀 @cloudwerxlab/gpt-image-1-mcp

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

🚀 快速开始

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

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

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

📋 前提条件

| 条件 | 详情 | |------|------| | Node.js | v14 或更高版本 | | OpenAI API密钥 | 具有访问 gpt-image-1 模型的权限 |

🔑 环境变量

| 变量 | 是否必需 | 描述 | |------|----------|------| | OPENAI_API_KEY | ✅ 是 | 你具有访问 gpt-image-1 模型权限的OpenAI API密钥 | | GPT_IMAGE_OUTPUT_DIR | ❌ 否 | 保存生成图像的自定义目录（默认为用户图片文件夹下的 gpt-image-1 子文件夹） |

💻 使用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

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

参数

| 参数 | 类型 | 是否必需 | 描述 | |-----------|------|----------|-------------| | prompt | 字符串 | 是 | 要生成的图像的文本描述（最多32,000个字符） | | size | 字符串 | 否 | 图像大小："1024x1024"（默认）、"1536x1024" 或 "1024x1536" | | quality | 字符串 | 否 | 图像质量："高"（默认）、"中" 或 "低" | | n | 整数 | 否 | 要生成的图像数量（1 - 10，默认：1） | | background | 字符串 | 否 | 背景样式："透明"、"不透明" 或 "自动"（默认） | | output_format | 字符串 | 否 | 输出格式："png"（默认）、"jpeg" 或 "webp" | | output_compression | 整数 | 否 | 压缩级别（0 - 100，默认：0） | | user | 字符串 | 否 | 用于OpenAI使用跟踪的用户标识符 | | moderation | 字符串 | 否 | 审核级别："低" 或 "自动"（默认） |

示例

<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

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

参数

| 参数 | 类型 | 是否必需 | 描述 | |-----------|------|----------|-------------| | image | 字符串、对象或数组 | 是 | 要编辑的图像（Base64字符串或文件路径对象） | | prompt | 字符串 | 是 | 所需编辑的文本描述（最多32,000个字符） | | mask | 字符串或对象 | 否 | 定义要编辑区域的掩码（Base64字符串或文件路径对象） | | size | 字符串 | 否 | 图像大小："1024x1024"（默认）、"1536x1024" 或 "1024x1536" | | quality | 字符串 | 否 | 图像质量："高"（默认）、"中" 或 "低" | | n | 整数 | 否 | 要生成的图像数量（1 - 10，默认：1） | | background | 字符串 | 否 | 背景样式："透明"、"不透明" 或 "自动"（默认） | | user | 字符串 | 否 | 用于OpenAI使用跟踪的用户标识符 |

使用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编码数据的编辑后图像。
  • 包括令牌使用情况和文件路径的元数据。

🔧 故障排除

🚨 常见问题

| 问题 | 解决方案 | |------|------| | 🖼️ MIME类型错误 | 确保图像文件具有与实际格式匹配的正确扩展名（.png、.jpg等）。服务器使用文件扩展名来确定MIME类型。 | | 🔑 API密钥问题 | 验证你的OpenAI API密钥是否正确，并且具有访问 gpt-image-1 模型的权限。检查是否意外包含了任何空格或特殊字符。 | | 🛠️ 构建错误 | 确保你安装了正确的TypeScript版本（v5.3.3或兼容版本），并且你的 tsconfig.json 配置正确。运行 npm install 以确保所有依赖项都已安装。 | | 📁 输出目录问题 | 检查进程是否具有对配置的输出目录的写入权限。如果相对路径不起作用，请尝试使用 GPT_IMAGE_OUTPUT_DIR 的绝对路径。 |

🔍 错误处理和报告

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

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

📄 许可证

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

许可证摘要

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

你可以自由地：

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

在以下条件下：

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

限制：

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

🙏 致谢

感谢以下方面的支持：

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

本项目由 CLOUDWERX 用心开发。

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client