Node.js (v14 or higher)

OpenAI API key with access to gpt-image-1

# 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

# 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:UsersusernamePicturesai-generated-images"

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

:: 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:UsersusernamePicturesai-generated-images

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

Step 1: Locate Settings File

• For Roo: c:Users<username>AppDataRoamingCodeUserglobalStoragerooveterinaryinc.roo-clinesettingsmcp_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%Cursormcp_settings.json (Windows)
• For Augment: ~/.config/augment/mcp_settings.json (Linux/macOS) or %APPDATA%Augmentmcp_settings.json (Windows)
• For Windsurf: ~/.config/windsurf/mcp_settings.json (Linux/macOS) or %APPDATA%Windsurfmcp_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": "sk-your-openai-api-key",
        "GPT_IMAGE_OUTPUT_DIR": "C:\Users\username\Pictures\ai-generated-images"
      }
    }
  }
}

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

📊 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

📂 Storage Location

• 🔹 Default Location: User's Pictures folder under gpt-image-1 subfolder (e.g., C:UsersusernamePicturesgpt-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

🖼️ 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.