OpenAI GPT Image MCP

1# openai-gpt-image-mcp
2 
3<p align="center">
4  <a href="https://www.npmjs.com/package/@modelcontextprotocol/sdk"><img src="https://img.shields.io/npm/v/@modelcontextprotocol/sdk?label=MCP%20SDK&color=blue" alt="MCP SDK"></a>
5  <a href="https://www.npmjs.com/package/openai"><img src="https://img.shields.io/npm/v/openai?label=OpenAI%20SDK&color=blueviolet" alt="OpenAI SDK"></a>
6  <a href="https://github.com/SureScaleAI/openai-gpt-image-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/SureScaleAI/openai-gpt-image-mcp?color=brightgreen" alt="License"></a>
7  <a href="https://github.com/SureScaleAI/openai-gpt-image-mcp/stargazers"><img src="https://img.shields.io/github/stars/SureScaleAI/openai-gpt-image-mcp?style=social" alt="GitHub stars"></a>
8  <a href="https://github.com/SureScaleAI/openai-gpt-image-mcp/actions"><img src="https://img.shields.io/github/actions/workflow/status/SureScaleAI/openai-gpt-image-mcp/main.yml?label=build&logo=github" alt="Build Status"></a>
9</p>
10 
11---
12 
13A Model Context Protocol (MCP) tool server for OpenAI's GPT-4o/gpt-image-1 image generation and editing APIs.
14 
15- **Generate images** from text prompts using OpenAI's latest models.
16- **Edit images** (inpainting, outpainting, compositing) with advanced prompt control.
17- **Supports**: Claude Desktop, Cursor, VSCode, Windsurf, and any MCP-compatible client.
18 
19---
20 
21## ✨ Features
22 
23- **create-image**: Generate images from a prompt, with advanced options (size, quality, background, etc).
24- **edit-image**: Edit or extend images using a prompt and optional mask, supporting both file paths and base64 input.
25- **File output**: Save generated images directly to disk, or receive as base64.
26 
27---
28 
29## 🚀 Installation
30 
31```sh
32git clone https://github.com/SureScaleAI/openai-gpt-image-mcp.git
33cd openai-gpt-image-mcp
34yarn install
35yarn build
36```
37 
38---
39 
40## 🔑 Configuration
41 
42Add to Claude Desktop or VSCode (including Cursor/Windsurf) config:
43 
44```json
45{
46  "mcpServers": {
47    "openai-gpt-image-mcp": {
48      "command": "node",
49      "args": ["/absolute/path/to/dist/index.js"],
50      "env": { "OPENAI_API_KEY": "sk-..." }
51    }
52  }
53}
54```
55 
56Also supports Azure deployments:
57 
58```json
59{
60  "mcpServers": {
61    "openai-gpt-image-mcp": {
62      "command": "node",
63      "args": ["/absolute/path/to/dist/index.js"],
64      "env": { 
65        "AZURE_OPENAI_API_KEY": "sk-...",
66        "AZURE_OPENAI_ENDPOINT": "my.endpoint.com",
67        "OPENAI_API_VERSION": "2024-12-01-preview"
68      }
69    }
70  }
71}
72```
73 
74Also supports supplying an environment files:
75 
76```json
77{
78  "mcpServers": {
79    "openai-gpt-image-mcp": {
80      "command": "node",
81      "args": ["/absolute/path/to/dist/index.js", "--env-file", "./deployment/.env"]
82    }
83  }
84}
85```
86 
87---
88 
89## ⚡ Advanced
90 
91- For `create-image`, set `n` to generate up to 10 images at once.
92- For `edit-image`, provide a mask image (file path or base64) to control where edits are applied.
93- Provide an environment file with `--env-file path/to/file/.env`
94- See `src/index.ts` for all options.
95 
96---
97 
98## 🧑‍💻 Development
99 
100- TypeScript source: `src/index.ts`
101- Build: `yarn build`
102- Run: `node dist/index.js`
103 
104---
105 
106## 📝 License
107 
108MIT
109 
110---
111 
112## 🩺 Troubleshooting
113 
114- Make sure your `OPENAI_API_KEY` is valid and has image API access.
115- You must have a [verified OpenAI organization](https://platform.openai.com/account/organization). After verifying, it can take 15–20 minutes for image API access to activate.
116- File paths must be absolute.
117  - **Unix/macOS/Linux**: Starting with `/` (e.g., `/path/to/image.png`)
118  - **Windows**: Drive letter followed by `:` (e.g., `C:/path/to/image.png` or `C:\path\to\image.png`)
119- For file output, ensure the directory is writable.
120- If you see errors about file types, check your image file extensions and formats.
121 
122---
123 
124## ⚠️ Limitations & Large File Handling
125 
126- **1MB Payload Limit:** MCP clients (including Claude Desktop) have a hard 1MB limit for tool responses. Large images (especially high-res or multiple images) can easily exceed this limit if returned as base64.
127- **Auto-Switch to File Output:** If the total image size exceeds 1MB, the tool will automatically save images to disk and return the file path(s) instead of base64. This ensures compatibility and prevents errors like `result exceeds maximum length of 1048576`.
128- **Default File Location:** If you do not specify a `file_output` path, images will be saved to `/tmp` (or the directory set by the `MCP_HF_WORK_DIR` environment variable) with a unique filename.
129- **Environment Variable:**
130  - `MCP_HF_WORK_DIR`: Set this to control where large images and file outputs are saved. Example: `export MCP_HF_WORK_DIR=/your/desired/dir`
131- **Best Practice:** For large or production images, always use file output and ensure your client is configured to handle file paths.
132 
133---
134 
135## 📚 References
136 
137- [OpenAI Images API Documentation](https://platform.openai.com/docs/api-reference/images)
138 
139---
140 
141## 🙏 Credits
142 
143- Built with [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
144- Uses [openai](https://www.npmjs.com/package/openai) Node.js SDK 
145- Built by [SureScale.ai](https://surescale.ai)
146- Contributions from [Axle Research and Technology](https://axleinfo.com/)