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

Server receives prompt and parameters

Calls OpenAI API using gpt-image-1 model

API returns base64-encoded images

Server saves images to configured directory

Returns formatted response with paths and metadata

Server receives image, prompt, and optional mask

For file paths, reads and prepares files for API

Uses direct curl command for proper MIME handling

API returns base64-encoded edited images

Server saves images to configured directory

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

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

参数

示例

gpt-image-1
create_image

{
  "prompt": "A futuristic city skyline at sunset, digital art",
  "size": "1024x1024",
  "quality": "high",
  "n": 1,
  "background": "auto"
}

响应

工具返回：

• 带有生成图像详细信息的格式化文本消息
• 图像为base64编码数据
• 元数据，包括令牌使用和文件路径

工具： create_image_edit

根据文本提示和可选遮罩编辑现有图像。

参数

Base64编码图像示例

gpt-image-1
create_image_edit

{
  "image": "BASE64_ENCODED_IMAGE_STRING",
  "prompt": "Add a small robot in the corner",
  "mask": "BASE64_ENCODED_MASK_STRING",
  "quality": "high"
}

文件路径示例

gpt-image-1
create_image_edit

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

响应

工具返回：

• 带有编辑图像详细信息的格式化文本消息
• 编辑后的图像为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. 错误格式：所有错误都将返回：

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

1. 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