Labsco
199-biotechnologies logo

OpenAI GPT Image

★ 1

from 199-biotechnologies

Generate and edit images using OpenAI's GPT-4o image generation and editing APIs with advanced prompt control.

🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup
#automation#ai-image#git#maps#security

openai-gpt-image-mcp

A Model Context Protocol (MCP) tool server for OpenAI's GPT-4o/gpt-image-1 image generation and editing APIs.

  • Generate images from text prompts using OpenAI's latest models.
  • Edit images (inpainting, outpainting, compositing) with advanced prompt control.
  • Supports: Claude Desktop, Cursor, VSCode, Windsurf, and any MCP-compatible client.

✨ Features

  • create-image: Generate images from a prompt, with advanced options (size, quality, background, etc).
  • edit-image: Edit or extend images using a prompt and optional mask, supporting both file paths and base64 input.
  • Aspect Ratio Support: Use common aspect ratios like 16:9, 9:16, 1:1, landscape, portrait, etc., which automatically map to supported sizes.
  • File output: Save generated images directly to disk, or receive as base64.
  • AI-Generated Filenames: The AI can provide descriptive filenames like "cat-playing-football.jpg" based on the image content.

⚡ Advanced

Aspect Ratio Support

The tools now support common aspect ratios that automatically map to OpenAI's supported sizes:

  • Square: 1:1, square, 4:3, 3:4 → 1024x1024
  • Landscape: 16:9, landscape, 3:2 → 1536x1024
  • Portrait: 9:16, portrait, 2:3 → 1024x1536
  • Auto: auto → Let OpenAI choose the best size

Example: Instead of specifying size: "1536x1024", you can use size: "16:9" or size: "landscape".

Other Options

  • For create-image, set n to generate up to 10 images at once.
  • For edit-image, provide a mask image (file path or base64) to control where edits are applied.
  • See src/index.ts for all options.

🧑‍💻 Development

  • TypeScript source: src/index.ts
  • Build: yarn build
  • Run: node dist/index.js

📝 License

MIT

⚠️ Limitations & Large File Handling

  • 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.
  • 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.
  • Default File Location:
    • macOS/Linux: Images are saved to ~/Pictures/gpt-image/ by default
    • Fallback: If the default directory cannot be created, images will be saved to /tmp (or the directory set by the MCP_HF_WORK_DIR environment variable)
    • Custom Path: You can always specify a custom file_output path to override the default
  • AI-Generated Filenames:
    • The AI can provide descriptive filenames through the filename parameter (e.g., "cat-playing-football", "sunset-over-mountains")
    • Filenames are automatically sanitized to prevent security issues
    • If multiple images are generated, an index is appended (e.g., "cat-playing-football_1.jpg", "cat-playing-football_2.jpg")
  • Environment Variable:
    • MCP_HF_WORK_DIR: Set this to control the fallback directory for large images and file outputs. Example: export MCP_HF_WORK_DIR=/your/desired/dir
  • Best Practice: For large or production images, always use file output and ensure your client is configured to handle file paths.

📚 References

🙏 Credits