{"id":28002902,"url":"https://github.com/cloudwerx-dev/gpt-image-1-mcp","last_synced_at":"2025-07-30T21:33:23.681Z","repository":{"id":291906845,"uuid":"979171876","full_name":"CLOUDWERX-DEV/gpt-image-1-mcp","owner":"CLOUDWERX-DEV","description":"A Model Context Protocol (MCP) server for generating and editing images using the OpenAI gpt-image-1 model.","archived":false,"fork":false,"pushed_at":"2025-05-07T06:43:03.000Z","size":3129,"stargazers_count":10,"open_issues_count":4,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-17T13:20:03.579Z","etag":null,"topics":["generation","gpt-image-1","image","mcp","mcp-server","openai"],"latest_commit_sha":null,"homepage":"http://cloudwerx.dev","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CLOUDWERX-DEV.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-07T05:32:30.000Z","updated_at":"2025-06-06T06:39:29.000Z","dependencies_parsed_at":"2025-05-07T06:44:26.476Z","dependency_job_id":null,"html_url":"https://github.com/CLOUDWERX-DEV/gpt-image-1-mcp","commit_stats":null,"previous_names":["cloudwerx-dev/gpt-image-1-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CLOUDWERX-DEV/gpt-image-1-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CLOUDWERX-DEV%2Fgpt-image-1-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CLOUDWERX-DEV%2Fgpt-image-1-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CLOUDWERX-DEV%2Fgpt-image-1-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CLOUDWERX-DEV%2Fgpt-image-1-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CLOUDWERX-DEV","download_url":"https://codeload.github.com/CLOUDWERX-DEV/gpt-image-1-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CLOUDWERX-DEV%2Fgpt-image-1-mcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267945171,"owners_count":24170215,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["generation","gpt-image-1","image","mcp","mcp-server","openai"],"created_at":"2025-05-09T01:44:05.262Z","updated_at":"2025-07-30T21:33:23.641Z","avatar_url":"https://github.com/CLOUDWERX-DEV.png","language":"JavaScript","funding_links":[],"categories":["Art \u0026 Culture"],"sub_categories":["How to Submit"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.png\" alt=\"GPT Image 1 MCP Logo\" width=\"200\"/\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003e@cloudwerxlab/gpt-image-1-mcp\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@cloudwerxlab/gpt-image-1-mcp\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@cloudwerxlab/gpt-image-1-mcp.svg\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@cloudwerxlab/gpt-image-1-mcp\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/@cloudwerxlab/gpt-image-1-mcp.svg\" alt=\"npm downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/CLOUDWERX-DEV/gpt-image-1-mcp/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/CLOUDWERX-DEV/gpt-image-1-mcp.svg\" alt=\"license\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org/\"\u003e\u003cimg src=\"https://img.shields.io/node/v/@cloudwerxlab/gpt-image-1-mcp.svg\" alt=\"node version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://cloudwerx.dev\"\u003e\u003cimg src=\"https://img.shields.io/badge/website-cloudwerx.dev-blue\" alt=\"Website\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  A Model Context Protocol (MCP) server for generating and editing images using the OpenAI \u003ccode\u003egpt-image-1\u003c/code\u003e model.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/OpenAI-GPT--Image--1-6E46AE\" alt=\"OpenAI GPT-Image-1\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/MCP-Compatible-00A3E0\" alt=\"MCP Compatible\"\u003e\n\u003c/p\u003e\n\n## 🚀 Quick Start\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@cloudwerxlab/gpt-image-1-mcp\"\u003e\u003cimg src=\"https://img.shields.io/badge/NPX-Ready-red.svg\" alt=\"NPX Ready\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003eRun this MCP server directly using NPX without installing it. \u003ca href=\"https://www.npmjs.com/package/@cloudwerxlab/gpt-image-1-mcp\"\u003eView on npm\u003c/a\u003e.\u003c/p\u003e\n\n```bash\nnpx -y @cloudwerxlab/gpt-image-1-mcp\n```\n\n\u003cp align=\"center\"\u003eThe \u003ccode\u003e-y\u003c/code\u003e flag automatically answers \"yes\" to any prompts that might appear during the installation process.\u003c/p\u003e\n\n### 📋 Prerequisites\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\" align=\"center\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/Node.js-v14+-339933?logo=node.js\u0026logoColor=white\" alt=\"Node.js v14+\"\u003e\n      \u003cp\u003eNode.js (v14 or higher)\u003c/p\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\" align=\"center\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/OpenAI-API_Key-412991?logo=openai\u0026logoColor=white\" alt=\"OpenAI API Key\"\u003e\n      \u003cp\u003eOpenAI API key with access to gpt-image-1\u003c/p\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### 🔑 Environment Variables\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth\u003eVariable\u003c/th\u003e\n    \u003cth\u003eRequired\u003c/th\u003e\n    \u003cth\u003eDescription\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eOPENAI_API_KEY\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e✅ Yes\u003c/td\u003e\n    \u003ctd\u003eYour OpenAI API key with access to the gpt-image-1 model\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eGPT_IMAGE_OUTPUT_DIR\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e❌ No\u003c/td\u003e\n    \u003ctd\u003eCustom directory for saving generated images (defaults to user's Pictures folder under \u003ccode\u003egpt-image-1\u003c/code\u003e subfolder)\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### 💻 Example Usage with NPX\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth\u003eOperating System\u003c/th\u003e\n    \u003cth\u003eCommand Line Example\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cstrong\u003eLinux/macOS\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\n\n```bash\n# Set your OpenAI API key\nexport OPENAI_API_KEY=sk-your-openai-api-key\n\n# Optional: Set custom output directory\nexport GPT_IMAGE_OUTPUT_DIR=/home/username/Pictures/ai-generated-images\n\n# Run the server with NPX\nnpx -y @cloudwerxlab/gpt-image-1-mcp\n```\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cstrong\u003eWindows (PowerShell)\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\n\n```powershell\n# Set your OpenAI API key\n$env:OPENAI_API_KEY = \"sk-your-openai-api-key\"\n\n# Optional: Set custom output directory\n$env:GPT_IMAGE_OUTPUT_DIR = \"C:\\Users\\username\\Pictures\\ai-generated-images\"\n\n# Run the server with NPX\nnpx -y @cloudwerxlab/gpt-image-1-mcp\n```\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cstrong\u003eWindows (Command Prompt)\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\n\n```cmd\n:: Set your OpenAI API key\nset OPENAI_API_KEY=sk-your-openai-api-key\n\n:: Optional: Set custom output directory\nset GPT_IMAGE_OUTPUT_DIR=C:\\Users\\username\\Pictures\\ai-generated-images\n\n:: Run the server with NPX\nnpx -y @cloudwerxlab/gpt-image-1-mcp\n```\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## 🔌 Integration with MCP Clients\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/VS_Code-MCP_Extension-007ACC?logo=visual-studio-code\u0026logoColor=white\" alt=\"VS Code MCP Extension\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Roo-Compatible-FF6B6B\" alt=\"Roo Compatible\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Cursor-Compatible-4C2889\" alt=\"Cursor Compatible\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Augment-Compatible-6464FF\" alt=\"Augment Compatible\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Windsurf-Compatible-00B4D8\" alt=\"Windsurf Compatible\"\u003e\n\u003c/div\u003e\n\n### 🛠️ Setting Up in an MCP Client\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n      \u003ch4\u003eStep 1: Locate Settings File\u003c/h4\u003e\n      \u003cul\u003e\n        \u003cli\u003eFor \u003cstrong\u003eRoo\u003c/strong\u003e: \u003ccode\u003ec:\\Users\\\u0026lt;username\u0026gt;\\AppData\\Roaming\\Code\\User\\globalStorage\\rooveterinaryinc.roo-cline\\settings\\mcp_settings.json\u003c/code\u003e\u003c/li\u003e\n        \u003cli\u003eFor \u003cstrong\u003eVS Code MCP Extension\u003c/strong\u003e: Check your extension documentation for the settings file location\u003c/li\u003e\n        \u003cli\u003eFor \u003cstrong\u003eCursor\u003c/strong\u003e: \u003ccode\u003e~/.config/cursor/mcp_settings.json\u003c/code\u003e (Linux/macOS) or \u003ccode\u003e%APPDATA%\\Cursor\\mcp_settings.json\u003c/code\u003e (Windows)\u003c/li\u003e\n        \u003cli\u003eFor \u003cstrong\u003eAugment\u003c/strong\u003e: \u003ccode\u003e~/.config/augment/mcp_settings.json\u003c/code\u003e (Linux/macOS) or \u003ccode\u003e%APPDATA%\\Augment\\mcp_settings.json\u003c/code\u003e (Windows)\u003c/li\u003e\n        \u003cli\u003eFor \u003cstrong\u003eWindsurf\u003c/strong\u003e: \u003ccode\u003e~/.config/windsurf/mcp_settings.json\u003c/code\u003e (Linux/macOS) or \u003ccode\u003e%APPDATA%\\Windsurf\\mcp_settings.json\u003c/code\u003e (Windows)\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n      \u003ch4\u003eStep 2: Add Configuration\u003c/h4\u003e\n      \u003cp\u003eAdd the following configuration to the \u003ccode\u003emcpServers\u003c/code\u003e object:\u003c/p\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"gpt-image-1\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@cloudwerxlab/gpt-image-1-mcp\"\n      ],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"PASTE YOUR OPEN-AI KEY HERE\",\n        \"GPT_IMAGE_OUTPUT_DIR\": \"OPTIONAL: PATH TO SAVE GENERATED IMAGES\"\n      }\n    }\n  }\n}\n```\n\n#### Example Configurations for Different Operating Systems\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth\u003eOperating System\u003c/th\u003e\n    \u003cth\u003eExample Configuration\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cstrong\u003eWindows\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"gpt-image-1\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cloudwerxlab/gpt-image-1-mcp\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"sk-your-openai-api-key\",\n        \"GPT_IMAGE_OUTPUT_DIR\": \"C:\\\\Users\\\\username\\\\Pictures\\\\ai-generated-images\"\n      }\n    }\n  }\n}\n```\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cstrong\u003eLinux/macOS\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"gpt-image-1\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cloudwerxlab/gpt-image-1-mcp\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"sk-your-openai-api-key\",\n        \"GPT_IMAGE_OUTPUT_DIR\": \"/home/username/Pictures/ai-generated-images\"\n      }\n    }\n  }\n}\n```\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003e **Note**: For Windows paths, use double backslashes (`\\\\`) to escape the backslash character in JSON. For Linux/macOS, use forward slashes (`/`).\n\n## ✨ Features\n\n\u003cdiv align=\"center\"\u003e\n  \u003ctable\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003ch3\u003e🎨 Core Tools\u003c/h3\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ccode\u003ecreate_image\u003c/code\u003e: Generate new images from text prompts\u003c/li\u003e\n          \u003cli\u003e\u003ccode\u003ecreate_image_edit\u003c/code\u003e: Edit existing images with text prompts and masks\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003ch3\u003e🚀 Key Benefits\u003c/h3\u003e\n        \u003cul\u003e\n          \u003cli\u003eSimple integration with MCP clients\u003c/li\u003e\n          \u003cli\u003eFull access to OpenAI's gpt-image-1 capabilities\u003c/li\u003e\n          \u003cli\u003eStreamlined workflow for AI image generation\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\u003c/div\u003e\n\n### 💡 Enhanced Capabilities\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n      \u003ch4\u003e📊 Output \u0026 Formatting\u003c/h4\u003e\n      \u003cul\u003e\n        \u003cli\u003e✅ \u003cstrong\u003eBeautifully Formatted Output\u003c/strong\u003e: Responses include emojis and detailed information\u003c/li\u003e\n        \u003cli\u003e✅ \u003cstrong\u003eAutomatic Image Saving\u003c/strong\u003e: All generated images saved to disk for easy access\u003c/li\u003e\n        \u003cli\u003e✅ \u003cstrong\u003eDetailed Token Usage\u003c/strong\u003e: View token consumption for each request\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003ch4\u003e⚙️ Configuration \u0026 Handling\u003c/h4\u003e\n      \u003cul\u003e\n        \u003cli\u003e✅ \u003cstrong\u003eConfigurable Output Directory\u003c/strong\u003e: Customize where images are saved\u003c/li\u003e\n        \u003cli\u003e✅ \u003cstrong\u003eFile Path Support\u003c/strong\u003e: Edit images using file paths instead of base64 encoding\u003c/li\u003e\n        \u003cli\u003e✅ \u003cstrong\u003eComprehensive Error Handling\u003c/strong\u003e: Detailed error reporting with specific error codes, descriptions, and troubleshooting suggestions\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## 🔄 How It Works\n\n\u003cdiv align=\"center\"\u003e\n  \u003ctable\u003e\n    \u003ctr\u003e\n      \u003cth align=\"center\"\u003e🖼️ Image Generation\u003c/th\u003e\n      \u003cth align=\"center\"\u003e✏️ Image Editing\u003c/th\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\n        \u003col\u003e\n          \u003cli\u003eServer receives prompt and parameters\u003c/li\u003e\n          \u003cli\u003eCalls OpenAI API using gpt-image-1 model\u003c/li\u003e\n          \u003cli\u003eAPI returns base64-encoded images\u003c/li\u003e\n          \u003cli\u003eServer saves images to configured directory\u003c/li\u003e\n          \u003cli\u003eReturns formatted response with paths and metadata\u003c/li\u003e\n        \u003c/ol\u003e\n      \u003c/td\u003e\n      \u003ctd\u003e\n        \u003col\u003e\n          \u003cli\u003eServer receives image, prompt, and optional mask\u003c/li\u003e\n          \u003cli\u003eFor file paths, reads and prepares files for API\u003c/li\u003e\n          \u003cli\u003eUses direct curl command for proper MIME handling\u003c/li\u003e\n          \u003cli\u003eAPI returns base64-encoded edited images\u003c/li\u003e\n          \u003cli\u003eServer saves images to configured directory\u003c/li\u003e\n          \u003cli\u003eReturns formatted response with paths and metadata\u003c/li\u003e\n        \u003c/ol\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\u003c/div\u003e\n\n### 📁 Output Directory Behavior\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003ch4\u003e📂 Storage Location\u003c/h4\u003e\n      \u003cul\u003e\n        \u003cli\u003e🔹 \u003cstrong\u003eDefault Location\u003c/strong\u003e: User's Pictures folder under \u003ccode\u003egpt-image-1\u003c/code\u003e subfolder (e.g., \u003ccode\u003eC:\\Users\\username\\Pictures\\gpt-image-1\u003c/code\u003e on Windows)\u003c/li\u003e\n        \u003cli\u003e🔹 \u003cstrong\u003eCustom Location\u003c/strong\u003e: Set via \u003ccode\u003eGPT_IMAGE_OUTPUT_DIR\u003c/code\u003e environment variable\u003c/li\u003e\n        \u003cli\u003e🔹 \u003cstrong\u003eFallback Location\u003c/strong\u003e: \u003ccode\u003e./generated-images\u003c/code\u003e (if Pictures folder can't be determined)\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003ch4\u003e🗂️ File Management\u003c/h4\u003e\n      \u003cul\u003e\n        \u003cli\u003e🔹 \u003cstrong\u003eDirectory Creation\u003c/strong\u003e: Automatically creates output directory if it doesn't exist\u003c/li\u003e\n        \u003cli\u003e🔹 \u003cstrong\u003eFile Naming\u003c/strong\u003e: Images saved with timestamped filenames (e.g., \u003ccode\u003eimage-2023-05-05T12-34-56-789Z.png\u003c/code\u003e)\u003c/li\u003e\n        \u003cli\u003e🔹 \u003cstrong\u003eCross-Platform\u003c/strong\u003e: Works on Windows, macOS, and Linux with appropriate Pictures folder detection\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Installation \u0026 Usage\n\n### NPM Package\n\nThis package is available on npm: [@cloudwerxlab/gpt-image-1-mcp](https://www.npmjs.com/package/@cloudwerxlab/gpt-image-1-mcp)\n\nYou can install it globally:\n\n```bash\nnpm install -g @cloudwerxlab/gpt-image-1-mcp\n```\n\nOr run it directly with npx as shown in the Quick Start section.\n\n### Tool: `create_image`\n\nGenerates a new image based on a text prompt.\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `prompt` | string | Yes | The text description of the image to generate (max 32,000 chars) |\n| `size` | string | No | Image size: \"1024x1024\" (default), \"1536x1024\", or \"1024x1536\" |\n| `quality` | string | No | Image quality: \"high\" (default), \"medium\", or \"low\" |\n| `n` | integer | No | Number of images to generate (1-10, default: 1) |\n| `background` | string | No | Background style: \"transparent\", \"opaque\", or \"auto\" (default) |\n| `output_format` | string | No | Output format: \"png\" (default), \"jpeg\", or \"webp\" |\n| `output_compression` | integer | No | Compression level (0-100, default: 0) |\n| `user` | string | No | User identifier for OpenAI usage tracking |\n| `moderation` | string | No | Moderation level: \"low\" or \"auto\" (default) |\n\n#### Example\n\n```xml\n\u003cuse_mcp_tool\u003e\n\u003cserver_name\u003egpt-image-1\u003c/server_name\u003e\n\u003ctool_name\u003ecreate_image\u003c/tool_name\u003e\n\u003carguments\u003e\n{\n  \"prompt\": \"A futuristic city skyline at sunset, digital art\",\n  \"size\": \"1024x1024\",\n  \"quality\": \"high\",\n  \"n\": 1,\n  \"background\": \"auto\"\n}\n\u003c/arguments\u003e\n\u003c/use_mcp_tool\u003e\n```\n\n#### Response\n\nThe tool returns:\n- A formatted text message with details about the generated image(s)\n- The image(s) as base64-encoded data\n- Metadata including token usage and file paths\n\n### Tool: `create_image_edit`\n\nEdits an existing image based on a text prompt and optional mask.\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `image` | string, object, or array | Yes | The image(s) to edit (base64 string or file path object) |\n| `prompt` | string | Yes | The text description of the desired edit (max 32,000 chars) |\n| `mask` | string or object | No | The mask that defines areas to edit (base64 string or file path object) |\n| `size` | string | No | Image size: \"1024x1024\" (default), \"1536x1024\", or \"1024x1536\" |\n| `quality` | string | No | Image quality: \"high\" (default), \"medium\", or \"low\" |\n| `n` | integer | No | Number of images to generate (1-10, default: 1) |\n| `background` | string | No | Background style: \"transparent\", \"opaque\", or \"auto\" (default) |\n| `user` | string | No | User identifier for OpenAI usage tracking |\n\n#### Example with Base64 Encoded Image\n\n```xml\n\u003cuse_mcp_tool\u003e\n\u003cserver_name\u003egpt-image-1\u003c/server_name\u003e\n\u003ctool_name\u003ecreate_image_edit\u003c/tool_name\u003e\n\u003carguments\u003e\n{\n  \"image\": \"BASE64_ENCODED_IMAGE_STRING\",\n  \"prompt\": \"Add a small robot in the corner\",\n  \"mask\": \"BASE64_ENCODED_MASK_STRING\",\n  \"quality\": \"high\"\n}\n\u003c/arguments\u003e\n\u003c/use_mcp_tool\u003e\n```\n\n#### Example with File Path\n\n```xml\n\u003cuse_mcp_tool\u003e\n\u003cserver_name\u003egpt-image-1\u003c/server_name\u003e\n\u003ctool_name\u003ecreate_image_edit\u003c/tool_name\u003e\n\u003carguments\u003e\n{\n  \"image\": {\n    \"filePath\": \"C:/path/to/your/image.png\"\n  },\n  \"prompt\": \"Add a small robot in the corner\",\n  \"mask\": {\n    \"filePath\": \"C:/path/to/your/mask.png\"\n  },\n  \"quality\": \"high\"\n}\n\u003c/arguments\u003e\n\u003c/use_mcp_tool\u003e\n```\n\n#### Response\n\nThe tool returns:\n- A formatted text message with details about the edited image(s)\n- The edited image(s) as base64-encoded data\n- Metadata including token usage and file paths\n\n## 🔧 Troubleshooting\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Support-Available-brightgreen\" alt=\"Support Available\"\u003e\n\u003c/div\u003e\n\n### 🚨 Common Issues\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth align=\"center\"\u003eIssue\u003c/th\u003e\n    \u003cth align=\"center\"\u003eSolution\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n      \u003ch4\u003e🖼️ MIME Type Errors\u003c/h4\u003e\n      \u003cp\u003eErrors related to image format or MIME type handling\u003c/p\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003cp\u003eEnsure image files have the correct extension (.png, .jpg, etc.) that matches their actual format. The server uses file extensions to determine MIME types.\u003c/p\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n      \u003ch4\u003e🔑 API Key Issues\u003c/h4\u003e\n      \u003cp\u003eAuthentication errors with OpenAI API\u003c/p\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003cp\u003eVerify 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.\u003c/p\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n      \u003ch4\u003e🛠️ Build Errors\u003c/h4\u003e\n      \u003cp\u003eIssues when building from source\u003c/p\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003cp\u003eEnsure you have the correct TypeScript version installed (v5.3.3 or compatible) and that your \u003ccode\u003etsconfig.json\u003c/code\u003e is properly configured. Run \u003ccode\u003enpm install\u003c/code\u003e to ensure all dependencies are installed.\u003c/p\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n      \u003ch4\u003e📁 Output Directory Issues\u003c/h4\u003e\n      \u003cp\u003eProblems with saving generated images\u003c/p\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003cp\u003eCheck if the process has write permissions to the configured output directory. Try using an absolute path for \u003ccode\u003eGPT_IMAGE_OUTPUT_DIR\u003c/code\u003e if relative paths aren't working.\u003c/p\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### 🔍 Error Handling and Reporting\n\nThe MCP server includes comprehensive error handling that provides detailed information when something goes wrong. When an error occurs:\n\n1. **Error Format**: All errors are returned with:\n   - A clear error message describing what went wrong\n   - The specific error code or type\n   - Additional context about the error when available\n\n2. **AI Assistant Behavior**: When using this MCP server with AI assistants:\n   - The AI will always report the full error message to help with troubleshooting\n   - The AI will explain the likely cause of the error in plain language\n   - The AI will suggest specific steps to resolve the issue\n\n## 📄 License\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"MIT License\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  This project is licensed under the MIT License - see the \u003ca href=\"LICENSE\"\u003eLICENSE\u003c/a\u003e file for details.\n\u003c/p\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eLicense Summary\u003c/summary\u003e\n\n  \u003cp\u003eThe 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.\u003c/p\u003e\n\n  \u003cp\u003e\u003cstrong\u003eYou are free to:\u003c/strong\u003e\u003c/p\u003e\n  \u003cul\u003e\n    \u003cli\u003eUse the software commercially\u003c/li\u003e\n    \u003cli\u003eModify the software\u003c/li\u003e\n    \u003cli\u003eDistribute the software\u003c/li\u003e\n    \u003cli\u003eUse and modify the software privately\u003c/li\u003e\n  \u003c/ul\u003e\n\n  \u003cp\u003e\u003cstrong\u003eUnder the following terms:\u003c/strong\u003e\u003c/p\u003e\n  \u003cul\u003e\n    \u003cli\u003eInclude the original copyright notice and the license notice in all copies or substantial uses of the work\u003c/li\u003e\n  \u003c/ul\u003e\n\n  \u003cp\u003e\u003cstrong\u003eLimitations:\u003c/strong\u003e\u003c/p\u003e\n  \u003cul\u003e\n    \u003cli\u003eThe authors provide no warranty with the software and are not liable for any damages\u003c/li\u003e\n  \u003c/ul\u003e\n\u003c/details\u003e\n\n## 🙏 Acknowledgments\n\n\u003cdiv align=\"center\"\u003e\n  \u003ctable\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003ca href=\"https://openai.com/\"\u003e\n          \u003cimg src=\"https://img.shields.io/badge/OpenAI-412991?logo=openai\u0026logoColor=white\" alt=\"OpenAI\"\u003e\n          \u003cp\u003eFor providing the gpt-image-1 model\u003c/p\u003e\n        \u003c/a\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003ca href=\"https://github.com/model-context-protocol/mcp\"\u003e\n          \u003cimg src=\"https://img.shields.io/badge/MCP-Protocol-00A3E0\" alt=\"MCP Protocol\"\u003e\n          \u003cp\u003eFor the protocol specification\u003c/p\u003e\n        \u003c/a\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/CLOUDWERX-DEV/gpt-image-1-mcp/issues\"\u003eReport Bug\u003c/a\u003e •\n    \u003ca href=\"https://github.com/CLOUDWERX-DEV/gpt-image-1-mcp/issues\"\u003eRequest Feature\u003c/a\u003e •\n    \u003ca href=\"https://cloudwerx.dev\"\u003eVisit Our Website\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\n    Developed with ❤️ by \u003ca href=\"https://cloudwerx.dev\"\u003eCLOUDWERX\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudwerx-dev%2Fgpt-image-1-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudwerx-dev%2Fgpt-image-1-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudwerx-dev%2Fgpt-image-1-mcp/lists"}