npm package: @ramarivera/gpt-image-1-mcp
Description: A Model Context Protocol server for OpenAI's gpt-image-1 model
Latest version: 1.2.0

<p align="center">
  <img src="logo.png" alt="GPT Image 1 MCP Logo" width="200"/>
</p>

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

<p align="center">
  <a href="https://www.npmjs.com/package/@ramarivera/gpt-image-1-mcp"><img src="https://img.shields.io/npm/v/@ramarivera/gpt-image-1-mcp.svg" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/@ramarivera/gpt-image-1-mcp"><img src="https://img.shields.io/npm/dm/@ramarivera/gpt-image-1-mcp.svg" alt="npm downloads"></a>
  <a href="https://github.com/ramarivera/gpt-image-1-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ramarivera/gpt-image-1-mcp.svg" alt="license"></a>
  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen" alt="node version"></a>
</p>

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

<p align="center">
  <img src="https://img.shields.io/badge/OpenAI-GPT--Image--1-6E46AE" alt="OpenAI GPT-Image-1">
  <img src="https://img.shields.io/badge/MCP-Compatible-00A3E0" alt="MCP Compatible">
</p>

## 🚀 Quick Start

<div align="center">
  <a href="https://www.npmjs.com/package/@ramarivera/gpt-image-1-mcp"><img src="https://img.shields.io/badge/NPX-Ready-red.svg" alt="NPX Ready"></a>
</div>

<p align="center">Run this MCP server directly using NPX without installing it.</p>

```bash
npx -y @ramarivera/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-v18+-339933?logo=node.js&logoColor=white" alt="Node.js v18+">
      <p>Node.js (v18 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>

```bash
# 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 @ramarivera/gpt-image-1-mcp
```
  </tr>
  <tr>
    <td><strong>Windows (PowerShell)</strong></td>
    <td>

```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 @ramarivera/gpt-image-1-mcp
```
  </tr>
  <tr>
    <td><strong>Windows (Command Prompt)</strong></td>
    <td>

```cmd
:: 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 @ramarivera/gpt-image-1-mcp
```
  </tr>
</table>

## 🔌 Integration with MCP Clients

<div align="center">
  <img src="https://img.shields.io/badge/Claude_Desktop-Compatible-00A67E" alt="Claude Desktop Compatible">
  <img src="https://img.shields.io/badge/VS_Code-MCP_Extension-007ACC?logo=visual-studio-code&logoColor=white" alt="VS Code MCP Extension">
  <img src="https://img.shields.io/badge/Cursor-Compatible-4C2889" alt="Cursor Compatible">
</div>

### 🛠️ Setting Up in an MCP Client

Add the following configuration to your MCP client's settings:

```json
{
  "mcpServers": {
    "gpt-image-1": {
      "command": "npx",
      "args": ["-y", "@ramarivera/gpt-image-1-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-your-openai-api-key"
      }
    }
  }
}
```

## ⚠️ Claude Desktop Compatibility

<div align="center">
  <img src="https://img.shields.io/badge/Claude_Desktop-Compatible-00A67E" alt="Claude Desktop Compatible">
</div>

### 📊 Response Size Limitation

Claude Desktop has a **~1MB response size limit**. Since gpt-image-1 generates minimum 1024x1024 images, base64-encoded responses will almost always exceed this limit and cause failures.

### ✅ Recommended Solution

**Always use `responseFormat: "paths"` when using this MCP server with Claude Desktop.**

This setting returns only the file paths where images are saved, instead of the base64-encoded image data. Images are always saved to disk regardless of this setting—the parameter only controls what's returned in the response payload.

### 📝 Example Usage with Claude Desktop

```xml
<use_mcp_tool>
<server_name>gpt-image-1</server_name>
<tool_name>create_image</tool_name>
<arguments>
{
  "prompt": "A beautiful sunset over mountains",
  "responseFormat": "paths"
}
</arguments>
</use_mcp_tool>
```

### 🔄 Response Format Options

| Value | Description | Use Case |
|-------|-------------|----------|
| `"paths"` | Returns only file paths | **Recommended for Claude Desktop** |
| `"base64"` | Returns only base64-encoded image data | When you need the raw image data and response size isn't limited |
| `"base64,paths"` | Returns both (default) | For backward compatibility; may fail on Claude Desktop |

## ✨ 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</li>
      </ul>
    </td>
  </tr>
</table>

## 📖 API Reference

### 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) |
| `moderation` | string | No | Moderation level: "low" or "auto" (default) |
| `responseFormat` | string | No | Response data: "paths" (recommended for Claude Desktop), "base64", or "base64,paths" (default) |

#### Example

```json
{
  "prompt": "A futuristic city skyline at sunset, digital art",
  "size": "1024x1024",
  "quality": "high",
  "responseFormat": "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) |
| `responseFormat` | string | No | Response data: "paths" (recommended for Claude Desktop), "base64", or "base64,paths" (default) |

#### Example with File Path

```json
{
  "image": {
    "filePath": "/path/to/your/image.png"
  },
  "prompt": "Add a small robot in the corner",
  "responseFormat": "paths"
}
```

## 📁 Output Directory Behavior

<table>
  <tr>
    <td width="50%">
      <h4>📂 Storage Location</h4>
      <ul>
        <li>🔹 <strong>Default</strong>: User's Pictures folder under <code>gpt-image-1/gpt-images</code> subfolder</li>
        <li>🔹 <strong>Custom</strong>: Set via <code>GPT_IMAGE_OUTPUT_DIR</code> environment variable</li>
        <li>🔹 <strong>Fallback</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>Auto-creation</strong>: Directory created automatically if it doesn't exist</li>
        <li>🔹 <strong>Naming</strong>: Timestamped filenames (e.g., <code>image-2024-01-15T12-34-56-789Z.png</code>)</li>
        <li>🔹 <strong>Cross-Platform</strong>: Works on Windows, macOS, and Linux</li>
      </ul>
    </td>
  </tr>
</table>

## 🔧 Troubleshooting

### 🚨 Common Issues

| Issue | Solution |
|-------|----------|
| **Response too large** | Use `responseFormat: "paths"` instead of default |
| **MIME Type Errors** | Ensure image files have correct extensions (.png, .jpg) |
| **API Key Issues** | Verify your OpenAI API key has access to gpt-image-1 |
| **Output Directory Issues** | Check write permissions or use absolute path for `GPT_IMAGE_OUTPUT_DIR` |

## 📄 License

<div align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
</div>

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

## 🙏 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/anthropics/anthropic-cookbook/tree/main/misc/model_context_protocol">
          <img src="https://img.shields.io/badge/MCP-Protocol-00A3E0" alt="MCP Protocol">
          <p>For the Model Context Protocol</p>
        </a>
      </td>
      <td align="center">
        <a href="https://github.com/CLOUDWERX-DEV/gpt-image-1-mcp">
          <img src="https://img.shields.io/badge/CLOUDWERX-Original-FF6B6B" alt="CLOUDWERX">
          <p>Original implementation</p>
        </a>
      </td>
    </tr>
  </table>
</div>