MCP Servers

GPT Image 1 MCP

A Model Context Protocol server that enables generating and editing images using OpenAI's gpt-image-1 model, allowing AI assistants to create and modify images from text prompts.

Tools

create_image

create_image_edit

README

<h1 align="center">@cloudwerxlab/gpt-image-1-mcp</h1>

<p align="center"> A Model Context Protocol (MCP) server for generating and editing images using the OpenAI <code>gpt-image-1</code> model. </p>

🚀 Quick Start

<p align="center">Run this MCP server directly using NPX without installing it. <a href="https://www.npmjs.com/package/@cloudwerxlab/gpt-image-1-mcp">View on npm</a>.</p>

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

<p align="center">The <code>-y</code> flag automatically answers "yes" to any prompts that might appear during the installation process.</p>

📋 Prerequisites

<table> <tr> <td width="50%" align="center"> <img src="https://img.shields.io/badge/Node.js-v14+-339933?logo=node.js&logoColor=white" alt="Node.js v14+"> <p>Node.js (v14 or higher)</p> </td> <td width="50%" align="center"> <img src="https://img.shields.io/badge/OpenAI-API_Key-412991?logo=openai&logoColor=white" alt="OpenAI API Key"> <p>OpenAI API key with access to gpt-image-1</p> </td> </tr> </table>

🔑 Environment Variables

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

💻 Example Usage with NPX

<table> <tr> <th>Operating System</th> <th>Command Line Example</th> </tr> <tr> <td><strong>Linux/macOS</strong></td> <td>

# 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

</tr> <tr> <td><strong>Windows (PowerShell)</strong></td> <td>

# 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

</tr> <tr> <td><strong>Windows (Command Prompt)</strong></td> <td>

:: 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

</tr> </table>

🔌 Integration with MCP Clients

🛠️ Setting Up in an MCP Client

<table> <tr> <td> <h4>Step 1: Locate Settings File</h4> <ul> <li>For <strong>Roo</strong>: <code>c:\Users<username>\AppData\Roaming\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json</code></li> <li>For <strong>VS Code MCP Extension</strong>: Check your extension documentation for the settings file location</li> <li>For <strong>Cursor</strong>: <code>~/.config/cursor/mcp_settings.json</code> (Linux/macOS) or <code>%APPDATA%\Cursor\mcp_settings.json</code> (Windows)</li> <li>For <strong>Augment</strong>: <code>~/.config/augment/mcp_settings.json</code> (Linux/macOS) or <code>%APPDATA%\Augment\mcp_settings.json</code> (Windows)</li> <li>For <strong>Windsurf</strong>: <code>~/.config/windsurf/mcp_settings.json</code> (Linux/macOS) or <code>%APPDATA%\Windsurf\mcp_settings.json</code> (Windows)</li> </ul> </td> </tr> <tr> <td> <h4>Step 2: Add Configuration</h4> <p>Add the following configuration to the <code>mcpServers</code> object:</p> </td> </tr> </table>

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

Example Configurations for Different Operating Systems

<table> <tr> <th>Operating System</th> <th>Example Configuration</th> </tr> <tr> <td><strong>Windows</strong></td> <td>

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

</tr> <tr> <td><strong>Linux/macOS</strong></td> <td>

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

</tr> </table>

Note: For Windows paths, use double backslashes (\\) to escape the backslash character in JSON. For Linux/macOS, use forward slashes (/).

✨ Features

<div align="center"> <table> <tr> <td align="center"> <h3>🎨 Core Tools</h3> <ul> <li><code>create_image</code>: Generate new images from text prompts</li> <li><code>create_image_edit</code>: Edit existing images with text prompts and masks</li> </ul> </td> <td align="center"> <h3>🚀 Key Benefits</h3> <ul> <li>Simple integration with MCP clients</li> <li>Full access to OpenAI's gpt-image-1 capabilities</li> <li>Streamlined workflow for AI image generation</li> </ul> </td> </tr> </table> </div>

💡 Enhanced Capabilities

<table> <tr> <td> <h4>📊 Output & Formatting</h4> <ul> <li>✅ <strong>Beautifully Formatted Output</strong>: Responses include emojis and detailed information</li> <li>✅ <strong>Automatic Image Saving</strong>: All generated images saved to disk for easy access</li> <li>✅ <strong>Detailed Token Usage</strong>: View token consumption for each request</li> </ul> </td> <td> <h4>⚙️ Configuration & Handling</h4> <ul> <li>✅ <strong>Configurable Output Directory</strong>: Customize where images are saved</li> <li>✅ <strong>File Path Support</strong>: Edit images using file paths instead of base64 encoding</li> <li>✅ <strong>Comprehensive Error Handling</strong>: Detailed error reporting with specific error codes, descriptions, and troubleshooting suggestions</li> </ul> </td> </tr> </table>

🔄 How It Works

<div align="center"> <table> <tr> <th align="center">🖼️ Image Generation</th> <th align="center">✏️ Image Editing</th> </tr> <tr> <td> <ol> <li>Server receives prompt and parameters</li> <li>Calls OpenAI API using gpt-image-1 model</li> <li>API returns base64-encoded images</li> <li>Server saves images to configured directory</li> <li>Returns formatted response with paths and metadata</li> </ol> </td> <td> <ol> <li>Server receives image, prompt, and optional mask</li> <li>For file paths, reads and prepares files for API</li> <li>Uses direct curl command for proper MIME handling</li> <li>API returns base64-encoded edited images</li> <li>Server saves images to configured directory</li> <li>Returns formatted response with paths and metadata</li> </ol> </td> </tr> </table> </div>

📁 Output Directory Behavior

<table> <tr> <td width="50%"> <h4>📂 Storage Location</h4> <ul> <li>🔹 <strong>Default Location</strong>: User's Pictures folder under <code>gpt-image-1</code> subfolder (e.g., <code>C:\Users\username\Pictures\gpt-image-1</code> on Windows)</li> <li>🔹 <strong>Custom Location</strong>: Set via <code>GPT_IMAGE_OUTPUT_DIR</code> environment variable</li> <li>🔹 <strong>Fallback Location</strong>: <code>./generated-images</code> (if Pictures folder can't be determined)</li> </ul> </td> <td width="50%"> <h4>🗂️ File Management</h4> <ul> <li>🔹 <strong>Directory Creation</strong>: Automatically creates output directory if it doesn't exist</li> <li>🔹 <strong>File Naming</strong>: Images saved with timestamped filenames (e.g., <code>image-2023-05-05T12-34-56-789Z.png</code>)</li> <li>🔹 <strong>Cross-Platform</strong>: Works on Windows, macOS, and Linux with appropriate Pictures folder detection</li> </ul> </td> </tr> </table>

Installation & Usage

NPM Package

This package is available on npm: @cloudwerxlab/gpt-image-1-mcp

You can install it globally:

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

Or run it directly with npx as shown in the Quick Start section.

Tool: `create_image`

Generates a new image based on a text prompt.

Parameters

Parameter	Type	Required	Description
`prompt`	string	Yes	The text description of the image to generate (max 32,000 chars)
`size`	string	No	Image size: "1024x1024" (default), "1536x1024", or "1024x1536"
`quality`	string	No	Image quality: "high" (default), "medium", or "low"
`n`	integer	No	Number of images to generate (1-10, default: 1)
`background`	string	No	Background style: "transparent", "opaque", or "auto" (default)
`output_format`	string	No	Output format: "png" (default), "jpeg", or "webp"
`output_compression`	integer	No	Compression level (0-100, default: 0)
`user`	string	No	User identifier for OpenAI usage tracking
`moderation`	string	No	Moderation level: "low" or "auto" (default)

Example

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

Response

The tool returns:

A formatted text message with details about the generated image(s)
The image(s) as base64-encoded data
Metadata including token usage and file paths

Tool: `create_image_edit`

Edits an existing image based on a text prompt and optional mask.

Parameters

Parameter	Type	Required	Description
`image`	string, object, or array	Yes	The image(s) to edit (base64 string or file path object)
`prompt`	string	Yes	The text description of the desired edit (max 32,000 chars)
`mask`	string or object	No	The mask that defines areas to edit (base64 string or file path object)
`size`	string	No	Image size: "1024x1024" (default), "1536x1024", or "1024x1536"
`quality`	string	No	Image quality: "high" (default), "medium", or "low"
`n`	integer	No	Number of images to generate (1-10, default: 1)
`background`	string	No	Background style: "transparent", "opaque", or "auto" (default)
`user`	string	No	User identifier for OpenAI usage tracking

Example with Base64 Encoded Image

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

Example with File Path

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

Response

The tool returns:

A formatted text message with details about the edited image(s)
The edited image(s) as base64-encoded data
Metadata including token usage and file paths

🔧 Troubleshooting

🚨 Common Issues

<table> <tr> <th align="center">Issue</th> <th align="center">Solution</th> </tr> <tr> <td> <h4>🖼️ MIME Type Errors</h4> <p>Errors related to image format or MIME type handling</p> </td> <td> <p>Ensure image files have the correct extension (.png, .jpg, etc.) that matches their actual format. The server uses file extensions to determine MIME types.</p> </td> </tr> <tr> <td> <h4>🔑 API Key Issues</h4> <p>Authentication errors with OpenAI API</p> </td> <td> <p>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.</p> </td> </tr> <tr> <td> <h4>🛠️ Build Errors</h4> <p>Issues when building from source</p> </td> <td> <p>Ensure you have the correct TypeScript version installed (v5.3.3 or compatible) and that your <code>tsconfig.json</code> is properly configured. Run <code>npm install</code> to ensure all dependencies are installed.</p> </td> </tr> <tr> <td> <h4>📁 Output Directory Issues</h4> <p>Problems with saving generated images</p> </td> <td> <p>Check if the process has write permissions to the configured output directory. Try using an absolute path for <code>GPT_IMAGE_OUTPUT_DIR</code> if relative paths aren't working.</p> </td> </tr> </table>

🔍 Error Handling and Reporting

The MCP server includes comprehensive error handling that provides detailed information when something goes wrong. When an error occurs:

Error Format: All errors are returned with:
- A clear error message describing what went wrong
- The specific error code or type
- Additional context about the error when available
AI Assistant Behavior: When using this MCP server with AI assistants:
- The AI will always report the full error message to help with troubleshooting
- The AI will explain the likely cause of the error in plain language
- The AI will suggest specific steps to resolve the issue

📄 License

<p align="center"> This project is licensed under the MIT License - see the <a href="LICENSE">LICENSE</a> file for details. </p>

<details> <summary>License Summary</summary>

<p>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.</p>

<p><strong>You are free to:</strong></p> <ul> <li>Use the software commercially</li> <li>Modify the software</li> <li>Distribute the software</li> <li>Use and modify the software privately</li> </ul>

<p><strong>Under the following terms:</strong></p> <ul> <li>Include the original copyright notice and the license notice in all copies or substantial uses of the work</li> </ul>

<p><strong>Limitations:</strong></p> <ul> <li>The authors provide no warranty with the software and are not liable for any damages</li> </ul> </details>

🙏 Acknowledgments

<div align="center"> <table> <tr> <td align="center"> <a href="https://openai.com/"> <img src="https://img.shields.io/badge/OpenAI-412991?logo=openai&logoColor=white" alt="OpenAI"> <p>For providing the gpt-image-1 model</p> </a> </td> <td align="center"> <a href="https://github.com/model-context-protocol/mcp"> <img src="https://img.shields.io/badge/MCP-Protocol-00A3E0" alt="MCP Protocol"> <p>For the protocol specification</p> </a> </td> </tr> </table> </div>

<div align="center"> <p> <a href="https://github.com/CLOUDWERX-DEV/gpt-image-1-mcp/issues">Report Bug</a> • <a href="https://github.com/CLOUDWERX-DEV/gpt-image-1-mcp/issues">Request Feature</a> • <a href="https://cloudwerx.dev">Visit Our Website</a> </p> </div>

<div align="center"> <p> Developed with ❤️ by <a href="https://cloudwerx.dev">CLOUDWERX</a> </p> </div>

Recommended Servers

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official

Featured

TypeScript

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Audiense Insights MCP Server

Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official

Featured

Local

graphlit-mcp-server

The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.

Official

Featured

TypeScript

Kagi MCP Server

An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

Official

Featured

Python

E2B

Using MCP to run code via e2b.

Official

Featured

Neon Database

MCP server for interacting with Neon Management API and databases

Official

Featured

Exa Search

A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.

Official

Featured

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official

Featured

GPT Image 1 MCP

Tools

README

🚀 Quick Start

📋 Prerequisites

🔑 Environment Variables

💻 Example Usage with NPX

🔌 Integration with MCP Clients

🛠️ Setting Up in an MCP Client

Example Configurations for Different Operating Systems

✨ Features

💡 Enhanced Capabilities

🔄 How It Works

📁 Output Directory Behavior

Installation & Usage

NPM Package

Tool: create_image

Parameters

Example

Response

Tool: create_image_edit

Parameters

Example with Base64 Encoded Image

Example with File Path

Response

🔧 Troubleshooting

🚨 Common Issues

🔍 Error Handling and Reporting

📄 License

🙏 Acknowledgments

Recommended Servers

Tool: `create_image`

Tool: `create_image_edit`