mcp-image

MCP Image Generator is an image generation MCP server that automatically enhances simple text prompts into high-quality images. It leverages Gemini-powered prompt optimization to add lighting, composition, atmosphere, and other photographic details, then passes these refined prompts to image generation models. The server supports multiple output formats and aspect ratios, and includes features like image-to-image editing and multi-image blending. You can integrate it with Cursor, Claude Code, Codex, or any MCP-compatible tool to streamline prompt-to-image workflows without manual prompt engineering.

To use it, configure your MCP tool to run the server via npx mcp-image (or equivalent). Provide a Gemini API key and an absolute path for image output. The prompt optimization component uses a Subject–Context–Style framework to fill in missing details while preserving your original intent, ensuring consistent, high-quality visuals across generations.

Prerequisites:

• Node.js 20 or higher
• npm (comes with Node.js)
• A Gemini API key
• An MCP-compatible AI tool (Cursor, Claude Code, Codex, etc.)

Installation steps:

1. Ensure Node.js 20+ is installed. Verify: node -v npm -v

2. Install and run the MCP Image server using npx (recommended for quick start):

npx -y mcp-image

This uses the npm package mcp-image to start the MCP server as a one-off command. If you prefer to install globally:

npm install -g mcp-image
mcp-image

3. Configure environment and output paths:

• Obtain a Gemini API key from Google AI Studio.
• Create an absolute output directory for generated images, for example: /abs/path/to/images

4. Optional per-tool configuration (examples):

• For Codex: add to your ~/.codex/config.toml [mcp_servers.mcp-image] command = "npx" args = ["-y", "mcp-image"]

  [mcp_servers.mcp-image.env] GEMINI_API_KEY = "your_gemini_api_key_here" IMAGE_OUTPUT_DIR = "/absolute/path/to/images"

• For Cursor and Claude Code: configure the mcp.json or appropriate setup as shown in the README (include GEMINI_API_KEY and IMAGE_OUTPUT_DIR in the env section).

Notes:

• Replace placeholders with your actual Gemini API key and desired output directory.
• The server is typically accessed via your MCP tool’s mcp configuration, which will handle spawning the npx mcp-image process as needed.

Tips and common issues:

• Always use absolute paths for IMAGE_OUTPUT_DIR to avoid path resolution issues.
• Do not hard-code your Gemini API key in public repos; use environment-specific configuration.
• If the server fails to start, ensure Node.js 20+ is installed and that npm can access the network to fetch the mcp-image package.
• The server supports multiple output formats (PNG, JPEG, WebP) and flexible aspect ratios; specify your desired output in your prompts or generation settings within your MCP tool.
• If you encounter authentication or quota errors with Gemini, review your API key permissions and usage limits in Google AI Studio.