AI导哈

GPT图像生成服务

一个基于OpenAI gpt-image-1模型的MCP服务器，用于生成和编辑图像，支持多种图像格式和自定义输出目录。

  • by CLOUDWERX-DEV
  • JavaScript
  • 本地部署
  • 18 星标
  • 更新于
在 GitHub 查看 CLOUDWERX-DEV/gpt-image-1-mcp

使用说明

@cloudwerxlab/gpt-image-1-mcp

A Model Context Protocol (MCP) server for generating and editing images using the OpenAI gpt-image-1 model.

🚀 快速开始

Run this MCP server directly using NPX without installing it. View on npm.

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

The -y flag automatically answers "yes" to any prompts that might appear during the installation process.

📋 先决条件

Node.js (v14 or higher)

OpenAI API key with access to gpt-image-1

🔑 环境变量

Variable Required Description
OPENAI_API_KEY ✅ Yes Your OpenAI API key with access to the gpt-image-1 model
GPT_IMAGE_OUTPUT_DIR ❌ No Custom directory for saving generated images (defaults to user's Pictures folder under gpt-image-1 subfolder)

💻 NPX使用示例

Operating System Command Line Example
Linux/macOS 
# Set your OpenAI API key
export OPENAI_API_KEY=sk-your-openai-api-key

# Optional: Set custom output directory
export GPT_IMAGE_OUTPUT_DIR=/home/username/Pictures/ai-generated-images

# Run the server with NPX
npx -y @cloudwerxlab/gpt-image-1-mcp
Windows (PowerShell) 
# Set your OpenAI API key
$env:OPENAI_API_KEY = "sk-your-openai-api-key"

# Optional: Set custom output directory
$env:GPT_IMAGE_OUTPUT_DIR = "C:\Users\username\Pictures\ai-generated-images"

# Run the server with NPX
npx -y @cloudwerxlab/gpt-image-1-mcp
Windows (Command Prompt) 
:: Set your OpenAI API key
set OPENAI_API_KEY=sk-your-openai-api-key

:: Optional: Set custom output directory
set GPT_IMAGE_OUTPUT_DIR=C:\Users\username\Pictures\ai-generated-images

:: Run the server with NPX
npx -y @cloudwerxlab/gpt-image-1-mcp

🔌 与MCP客户端集成

🛠️ 在MCP客户端中设置

Step 1: Locate Settings File

  • For Roo: c:\Users\<username>\AppData\Roaming\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json
  • For VS Code MCP Extension: Check your extension documentation for the settings file location
  • For Cursor: ~/.config/cursor/mcp_settings.json (Linux/macOS) or %APPDATA%\Cursor\mcp_settings.json (Windows)
  • For Augment: ~/.config/augment/mcp_settings.json (Linux/macOS) or %APPDATA%\Augment\mcp_settings.json (Windows)
  • For Windsurf: ~/.config/windsurf/mcp_settings.json (Linux/macOS) or %APPDATA%\Windsurf\mcp_settings.json (Windows)

Step 2: Add Configuration

Add the following configuration to the mcpServers object:

 
{
  "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"
      }
    }
  }
}

不同操作系统的示例配置

Operating System Example Configuration
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，使用正斜杠(/).

✨ 特性

🎨 Core Tools

  • create_image: Generate new images from text prompts
  • create_image_edit: Edit existing images with text prompts and masks

🚀 Key Benefits

  • Simple integration with MCP clients
  • Full access to OpenAI's gpt-image-1 capabilities
  • Streamlined workflow for AI image generation

💡 增强功能

📊 Output & Formatting

  • ✅ Beautifully Formatted Output: Responses include emojis and detailed information
  • ✅ Automatic Image Saving: All generated images saved to disk for easy access
  • ✅ Detailed Token Usage: View token consumption for each request

⚙️ Configuration & Handling

  • ✅ Configurable Output Directory: Customize where images are saved
  • ✅ File Path Support: Edit images using file paths instead of base64 encoding
  • ✅ Comprehensive Error Handling: Detailed error reporting with specific error codes, descriptions, and troubleshooting suggestions

🔄 运作原理

🖼️ Image Generation ✏️ Image Editing
  1. Server receives prompt and parameters
  2. Calls OpenAI API using gpt-image-1 model
  3. API returns base64-encoded images
  4. Server saves images to configured directory
  5. Returns formatted response with paths and metadata
  1. Server receives image, prompt, and optional mask
  2. For file paths, reads and prepares files for API
  3. Uses direct curl command for proper MIME handling
  4. API returns base64-encoded edited images
  5. Server saves images to configured directory
  6. Returns formatted response with paths and metadata

📁 输出目录行为

📂 Storage Location

  • 🔹 Default Location: User's Pictures folder under gpt-image-1 subfolder (e.g., C:\Users\username\Pictures\gpt-image-1 on Windows)
  • 🔹 Custom Location: Set via GPT_IMAGE_OUTPUT_DIR environment variable
  • 🔹 Fallback Location: ./generated-images (if Pictures folder can't be determined)

🗂️ File Management

  • 🔹 Directory Creation: Automatically creates output directory if it doesn't exist
  • 🔹 File Naming: Images saved with timestamped filenames (e.g., image-2023-05-05T12-34-56-789Z.png)
  • 🔹 Cross-Platform: Works on Windows, macOS, and Linux with appropriate Pictures folder detection

安装与使用

NPM包

这个包可以在npm上找到： @cloudwerxlab/gpt-image 1-mcp

您可以全局安装它：

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

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

工具： create_image

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

参数

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

示例

<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 string、object或array 是 要编辑的图像（base64字符串或文件路径对象）
prompt string 是 所需编辑的文本描述（最多32000个字符）
mask string或object 否 定义要编辑区域的掩码（base64字符串或文件路径对象）
size string 否 图像大小：“1024x1024”（默认）、“1536x1024”或“1024x1536”
quality string 否 图像质量：“高”（默认）、“中”或“低”
n integer 否 要生成的图像数量（1-10，默认值：1）
background string 否 背景样式：“透明”、“不透明”或“自动”（默认）
user string 否 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编码数据
  • 元数据，包括令牌使用和文件路径

🔧 故障排除

🚨 常见问题

Issue Solution

🖼️ MIME Type Errors

Errors related to image format or MIME type handling

Ensure image files have the correct extension (.png, .jpg, etc.) that matches their actual format. The server uses file extensions to determine MIME types.

🔑 API Key Issues

Authentication errors with OpenAI API

Verify your OpenAI API key is correct and has access to the gpt-image-1 model. Check for any spaces or special characters that might have been accidentally included.

🛠️ Build Errors

Issues when building from source

Ensure you have the correct TypeScript version installed (v5.3.3 or compatible) and that your tsconfig.json is properly configured. Run npm install to ensure all dependencies are installed.

📁 Output Directory Issues

Problems with saving generated images

Check if the process has write permissions to the configured output directory. Try using an absolute path for GPT_IMAGE_OUTPUT_DIR if relative paths aren't working.

🔍 错误处理和报告

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

  1. 错误格式：所有错误都将返回：

    • 一条明确的错误消息，描述出了什么问题
    • 特定错误代码或类型
    • 有关错误的其他上下文（如果可用）

  2. AI助手行为：将此MCP服务器与AI助手一起使用时：

    • AI将始终报告完整的错误消息，以帮助进行故障排除
    • 人工智能将用通俗易懂的语言解释错误的可能原因
    • 人工智能将建议解决该问题的具体步骤

📄 许可证

This project is licensed under the MIT License - see the LICENSE file for details.

License Summary

The MIT License is a permissive license that is short and to the point. It lets people do anything with your code with proper attribution and without warranty.

You are free to:

  • Use the software commercially
  • Modify the software
  • Distribute the software
  • Use and modify the software privately

Under the following terms:

  • Include the original copyright notice and the license notice in all copies or substantial uses of the work

Limitations:

  • The authors provide no warranty with the software and are not liable for any damages

🙏 致谢

For providing the gpt-image-1 model

For the protocol specification

Report Bug • Request Feature • Visit Our Website

Developed with ❤️ by CLOUDWERX

相关 MCP