Skip to content
Back to search

gpt-image-2-mcp

Local MCP server for ChatGPT image generation.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lownamlee--gpt-image-2-mcp/badge.svg)](/listings/lownamlee--gpt-image-2-mcp)

HTML

<a href="/listings/lownamlee--gpt-image-2-mcp"><img src="/api/listings/lownamlee--gpt-image-2-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Add the server to your MCP client:

{
  "mcpServers": {
    "gpt-image-2": {
      "command": "npx",
      "args": ["-y", "@ramlyburger/gpt-image-2-mcp"],
      "env": {
        "GPT_IMAGE_BACKEND": "chatgpt-web"
      }
    }
  }
}

That is enough for the ChatGPT website mode. The first run opens ChatGPT so you can sign in or complete verification. After that, the local profile can be reused across restarts.

For direct API generation, set `OPENAI_API_KEY` and change `GPT_IMAGE_BACKEND` to `api`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 220 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # @ramlyburger/gpt-image-2-mcp
  2. <p align="center">
  3. <a href="https://www.npmjs.com/package/@ramlyburger/gpt-image-2-mcp"><img src="https://img.shields.io/npm/v/@ramlyburger/gpt-image-2-mcp?logo=npm&label=npm" alt="npm version" /></a>
  4. <a href="https://www.npmjs.com/package/@ramlyburger/gpt-image-2-mcp"><img src="https://img.shields.io/npm/dm/@ramlyburger/gpt-image-2-mcp?logo=npm&label=downloads" alt="npm downloads" /></a>
  5. <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=nodedotjs&logoColor=white" alt="Node.js 20 or newer" /></a>
  6. <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-server-6f42c1" alt="Model Context Protocol server" /></a>
  7. <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license" /></a>
  8. </p>
  9. <p align="center">
  10. <img src="./assets/banner.png" alt="GPT Image 2 MCP banner showing prompts flowing through an MCP server into generated images" width="980" />
  11. </p>
  12. Turn any MCP-compatible AI client into an image generator. Send a normal prompt, choose a backend mode, and get real saved image files back.
  13. ## Popularity
  14. <p align="center">
  15. <img src="./assets/pulsemcp-popularity.png" alt="Pulse MCP popularity ranking for GPT Image 2" width="980" />
  16. </p>
  17. PulseMCP: [https://www.pulsemcp.com/servers/ramlyburger-gpt-image-2](https://www.pulsemcp.com/servers/ramlyburger-gpt-image-2)
  18. ## 🖼️ What It Does
  19. - ✍️ **Prompt in:** ask for an image from your MCP client.
  20. - ⚙️ **MCP server runs:** `gpt-image-2-mcp` handles the image request.
  21. - 💾 **Files out:** every result includes `output_dir`, `image_path`, and metadata.
  22. - 🔐 **No ChatGPT API key needed** in `chatgpt-web` mode. You only need a ChatGPT account and a successful sign-in at [chatgpt.com](https://chatgpt.com/).
  23. <p align="center">
  24. <img src="./assets/quick-flow.png" alt="Beginner-friendly flow from prompt to GPT Image 2 MCP to saved images" width="980" />
  25. </p>
  26. ## 🚀 Quick Start
  27. Add the server to your MCP client:
  28. ```json
  29. {
  30. "mcpServers": {
  31. "gpt-image-2": {
  32. "command": "npx",
  33. "args": ["-y", "@ramlyburger/gpt-image-2-mcp"],
  34. "env": {
  35. "GPT_IMAGE_BACKEND": "chatgpt-web"
  36. }
  37. }
  38. }
  39. }
  40. ```
  41. That is enough for the ChatGPT website mode. The first run opens ChatGPT so you can sign in or complete verification. After that, the local profile can be reused across restarts.
  42. For direct API generation, set `OPENAI_API_KEY` and change `GPT_IMAGE_BACKEND` to `api`.
  43. ## 🧭 Pick A Mode
  44. | Mode | What you need | Best when | Notes |
  45. | --- | --- | --- | --- |
  46. | `chatgpt-web` | A ChatGPT account and sign-in at `chatgpt.com` | You want a simple setup without a ChatGPT API key | Good beginner default |
  47. | `api` | `OPENAI_API_KEY` | You want the direct API path | Uses `gpt-image-2` |
  48. | `auto` | Preferably an API key; otherwise a usable ChatGPT website session | You want API first with fallback behavior | Tries API first, then falls back only when the API backend is unavailable |
  49. ## 🎬 Demo
  50. [![Demo](./assets/demo.gif)](./assets/demo.mp4)
  51. Click the GIF to open the full MP4.
  52. ## 🧰 Tool Surface
  53. - `generate_image(prompt, backend?, n?, size?, quality?, output_format?, conversation_mode?, timeout_seconds?)`
  54. - `backend_status(backend?)`
  55. - `browser_visibility(action?, start_browser?)`
  56. Backend values are `api`, `chatgpt-web`, or `auto`.
  57. Use `conversation_mode="new"` or `conversation_mode="continue"` with the ChatGPT website mode.
  58. ## 📄 Technical Reference
  59. The section below is the implementation-oriented view.
  60. ### Figure 1. System Model
  61. ```mermaid
  62. flowchart LR
  63. A["MCP client"] --> B["gpt-image-2-mcp<br/>stdio server"]
  64. B --> C["Input validation<br/>Zod schemas"]
  65. C --> D{"Backend selection"}
  66. D --> E["OpenAI API mode"]
  67. D --> F["ChatGPT website mode"]
  68. E --> G["Saved image files<br/>metadata.json"]
  69. F --> G
  70. ```
  71. <p align="center">
  72. <img src="./assets/technical-figure.png" alt="Academic paper-style architecture figure for GPT Image 2 MCP" width="980" />
  73. </p>
  74. ### Abstract
  75. `gpt-image-2-mcp` is a small TypeScript MCP server that exposes image generation through a narrow tool contract. The server validates MCP tool input, resolves the requested backend, persists generated artifacts to disk, and returns structured metadata plus image content to the caller.
  76. ### Method
  77. The implementation follows a five-stage pipeline:
  78. 1. parse and validate MCP tool input
  79. 2. resolve the backend from `api`, `chatgpt-web`, or `auto`
  80. 3. execute the selected image-generation path
  81. 4. write generated images and `metadata.json` to a prompt-derived output directory
  82. 5. return `output_dir`, `image_path`, `images`, and backend metadata
  83. The `auto` mode attempts the API backend first and falls back to `chatgpt-web` only when the API backend is unavailable.
  84. ### Artifact Model
  85. Each generation creates one output directory. Images are written as numbered files such as `image-01.png`, and metadata is written beside them.
  86. Default output roots:
  87. ```text
  88. Windows: %LOCALAPPDATA%\gpt-image-2-mcp\output\chatgpt-images
  89. macOS: ~/Library/Application Support/gpt-image-2-mcp/output/chatgpt-images
  90. Linux: ${XDG_DATA_HOME:-~/.local/share}/gpt-image-2-mcp/output/chatgpt-images
  91. ```
  92. Operational notes:
  93. - `backend_status` returns the effective `output_root`
  94. - `generate_image` returns `output_dir`, `image_path`, and the full `images` array
  95. - image filenames are deterministic within one output directory: `image-01`, `image-02`, and so on
  96. - metadata is written as JSON alongside the image files
  97. ### ChatGPT Website Mode
  98. Run the server in ChatGPT website mode:
  99. ```powershell
  100. $env:GPT_IMAGE_BACKEND = "chatgpt-web"
  101. node dist/index.js
  102. ```
  103. When the server starts, it opens ChatGPT in Chrome or Edge. Sign in or complete verification there. Once the normal composer is visible, the session is ready for tool calls. No ChatGPT API key is required for this mode.
  104. The local ChatGPT sign-in profile is stored under the same per-user app data directory by default. Override it with:
  105. ```powershell
  106. $env:CHATGPT_WEB_PROFILE_DIR = "C:\path\to\profile"
  107. ```
  108. Optional settings:
  109. ```powershell
  110. $env:CHATGPT_WEB_LOGIN_TIMEOUT_SECONDS = "900"
  111. $env:CHATGPT_HIDE_WINDOW = "0"
  112. ```
  113. `CHATGPT_HIDE_WINDOW` defaults to enabled. The ChatGPT window stays visible for login or verification, then hides after `chatgpt.com` is ready. Use `0` if you want the window to remain visible after sign-in.
  114. ### API Mode
  115. Run the server in direct API mode:
  116. ```powershell
  117. $env:OPENAI_API_KEY = "sk-..."
  118. $env:GPT_IMAGE_BACKEND = "api"
  119. node dist/index.js
  120. ```
  121. This mode uses the configured OpenAI image model directly. By default the model is `gpt-image-2`, and the selected output format can be `png`, `jpeg`, or `webp`.
  122. ### Tool Contract
  123. `generate_image` returns a structured result with these important fields:
  124. - `status`
  125. - `requested_backend`
  126. - `backend`
  127. - `fallback_from`
  128. - `prompt`
  129. - `output_dir`
  130. - `image_path`
  131. - `images`
  132. - `metadata`
  133. `backend_status` returns readiness and configuration information for the selected backend or for both backends when `auto` is requested.
  134. `browser_visibility` controls the visibility of the ChatGPT window and can also start the ChatGPT session when requested.
  135. ### Local Development
  136. The TypeScript MCP server is the only supported entry point.
  137. Install and build:
  138. ```powershell
  139. npm install
  140. npm run build
  141. ```
  142. Useful local commands:
  143. ```powershell
  144. npm run typecheck
  145. npm run build
  146. npm run start
  147. ```
  148. ### Repository Notes
  149. - `src/index.ts` registers the MCP tools
  150. - `src/config.ts` resolves environment-driven configuration
  151. - `src/backends/` contains backend implementations and selection logic
  152. - `src/output.ts` is responsible for output-directory naming and file writes
  153. The public MCP surface stays intentionally small while backend-specific behavior remains isolated in the backend layer.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.