GPT-Image-Forge-MCP-Adapter

This node service implements the Model Context Protocol (MCP) interface layer for accessing OpenAI's generative vision APIs (GPT-4o and gpt-image-1) for both initial image synthesis and subsequent iterative refinement.

Synthesize Visuals: Render novel imagery from natural language descriptions using OpenAI's most current architectures.
Refine Imagery: Perform localized modifications such as inpainting, extending boundaries (outpainting), or compositing, guided by precise textual context.
Compatibility: Seamlessly integrates with ecosystem tools including Claude Desktop, Cursor, VSCode environments, Windsurf, and all other MCP-compliant consumer applications.

✨ Core Capabilities

visual-generation: Formulate new pictures based on a descriptive input string, with fine-grained tuning over aspects like resolution, fidelity, and background attributes.
visual-modification: Alter existing pictures, optionally supplying a stencil mask to specify edit regions. Accepts input media via local file reference or inline base64 encoding.
Output Modality: Images can be persisted to the local filesystem or transmitted directly as a base64-encoded payload.

🚀 Deployment Procedure

git clone https://github.com/SureScaleAI/openai-gpt-image-mcp.git
cd openai-gpt-image-mcp
yarn install
yarn build

🔑 Configuration Prerequisites

Integrate into your client configuration (e.g., Claude Desktop, VSCode setup for Cursor/Windsurf):

{
  "mcpServers": {
    "gpt-image-forge-mcp-adapter": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": { "OPENAI_API_KEY": "sk-YOUR_KEY_HERE" }
    }
  }
}

Alternatively, for Azure OpenAI Service deployments:

{
  "mcpServers": {
    "gpt-image-forge-mcp-adapter": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": { 
        "AZURE_OPENAI_API_KEY": "sk-AZURE_KEY",
        "AZURE_OPENAI_ENDPOINT": "my.azure.endpoint.com",
        "OPENAI_API_VERSION": "2024-12-01-preview"
      }
    }
  }
}

Environment file injection is also supported:

{
  "mcpServers": {
    "gpt-image-forge-mcp-adapter": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js", "--env-file", "./deployment/.env"]
    }
  }
}

⚡ Advanced Tuning

For visual-generation, utilize the n parameter to request batch creation of up to 10 distinct images concurrently.
For visual-modification, supplying a mask (either file path reference or base64 content) constrains the generative edits to the designated regions.
Environment configuration files can be loaded using the --env-file path/to/file/.env runtime argument.
Comprehensive parameter exposition is detailed within src/index.ts.

🧑‍💻 Development Lifecycle

Source Code Location: src/index.ts
Compilation: yarn build
Execution Test: node dist/index.js

📝 Licensing

This project operates under the MIT license.

🩺 Diagnostic Guidance

Verify that your OPENAI_API_KEY is valid and authorized for vision model access.
Ensure your OpenAI organization account is verified. API access activation may require a provisioning delay of 15–20 minutes post-verification.
File system references must employ absolute paths:
POSIX Systems (Unix/macOS/Linux): Must commence with / (e.g., /usr/local/assets/photo.png)
Windows: Must include the drive identifier (e.g., D:/data/image.jpg or C:\temp\file.png)
For saved output, confirm the target directory possesses the necessary write permissions.
Mismatches in expected image formats or file extensions can lead to type errors.

⚠️ Constraints & Large Data Handling

Response Size Cap: MCP clients, notably Claude Desktop, enforce a strict 1MB ceiling on data returned in the tool response payload. High-resolution or multi-image outputs, when encoded as base64, readily surpass this limit.
Automatic Fallback: If the aggregate size of the resulting images is predicted to exceed 1MB, the tool automatically switches to disk persistence, returning file path(s) rather than base64 strings, thus averting overflow errors like result exceeds maximum length of 1048576.
Default Persistence Directory: In the absence of an explicit file_output specification, generated visuals are saved within the /tmp directory (or the location specified by the MCP_HF_WORK_DIR environment variable) utilizing a collision-resistant filename.
Environment Variable Override:
MCP_HF_WORK_DIR: Designate an alternative staging location for persistent outputs. Example: export MCP_HF_WORK_DIR=/mnt/shared_storage/images
Recommended Practice: For any high-fidelity or mission-critical imagery, configure the tool to use file output exclusively and ensure the consuming client is prepared to resolve file path references.