Image Generator
About
Image generation and editing with advanced features like multi-image blending and character consistency
Details
- Author
- shinpr
- Categories
- Other, AI
Jump to
Setup
Install Image Generator in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/shinpr/mcp-image
Follow the installation instructions in the repository README, then restart your MCP client.
Generate and edit images from Cursor, Claude Code, Codex, or any MCP-compatible tool. Supports Google Gemini, OpenAI GPT Image, and BytePlus Seedream.
This MCP server turns a plain-language request into an image file. It adds relevant photographic details such as lighting, camera angle, materials, and palette, then returns the saved image as an MCP resource.
You: "a roast chicken for a recipe page, partway through carving so you can see how juicy it is" ↓ Your AI assistant sends the request to mcp-image ↓ Prompt enhancement adds relevant photographic details (subject, lighting, camera, and palette) ↓ The selected provider generates the image (using the configured grounding, consistency, and resolution options) ↓ Saved file, returned as an MCP resource
Your AI assistant supplies the style, purpose, and context from your request. mcp-image fills in missing visual details and selects the generation settings.
The prompt optimizer uses aSubject–Context–Styleframework. It runs on Gemini 2.5 Flash by default, OpenAI Responses whenIMAGE_PROVIDER=openai, or ModelArk Responses whenIMAGE_PROVIDER=seedream. It adds missing details about the subject, environment, lighting, and camera work while keeping the details already present in the request. Detailed prompts receive fewer changes.
You write:"a photo of a roast chicken dinner for a recipe site. it should look like it was actually cooked, and it should be partway through being carved so you can tell how juicy it is"
What the server sends to the image model:"...a beautifully roasted whole chicken,golden-brown and glistening, resting on a rustic wooden cutting board. One leg is partially carved, revealingtender, succulent white meat and rich, glistening juices poolingaround the carving knife ...shallow depth of fieldto keep the focus sharply on the carved chicken."
- for a recipe site→ one subject, with everything else kept subordinate
- actually cooked→ juices spread across the board, uneven browning
- partway through being carved→ the cut face, with slices laid beside it
- how juicy it is→ close framing and shallow depth of field on the cut
SetSKIP_PROMPT_ENHANCEMENT=trueto send your prompt through unchanged.
- Prompt enhancement: Adds lighting, composition, camera, and palette details using the selected provider's text model.
- Image providers: SetIMAGE_PROVIDER=openaifor OpenAI GPT Image orIMAGE_PROVIDER=seedreamfor BytePlus Seedream through ModelArk.
- Quality presets: Selectfast,balanced, orquality. Each provider maps these values to a supported model route.See Quality Presets.
- Image editing: Edit an existing image with natural-language instructions while retaining its style and visual details.
- Resolution controls: Request up to 4K, depending on the provider and quality route.
- Aspect ratios: Supports formats from square (1:1) to ultra-wide (21:9) and ultra-tall (1:8).
- Character consistency: Keep a character's appearance consistent across storyboards, product shots, or a series of images.
- Provider-specific options:
- Google Search grounding for real-time factual accuracy with the Gemini provider
- World knowledge for photorealistic depictions of historical figures, landmarks, and factual scenarios
- Prompt-level blending guidance for composite scenes
- Purpose-aware generation (e.g., "cookbook cover" produces different results than "social media post")
- Node.js22 or higher
- Gemini API Key- Get yours atGoogle AI Studiofor the default Gemini provider
- OpenAI API Key- Get yours fromOpenAIwhen usingIMAGE_PROVIDER=openai
- BytePlus ModelArk API Key- Create one in theAP region ModelArk consolewhen usingIMAGE_PROVIDER=seedream
- An MCP-compatible AI tool:Cursor,Claude Code,Codex, or others
- Basic terminal/command line knowledge
To use OpenAI instead, get an OpenAI API key and set:
IMAGE_PROVIDER=openai OPENAI_API_KEY=your_openai_api_key_here
OpenAI mode requires organization verification. SeeUsing the OpenAI providerfor setup details and feature differences.
To use BytePlus Seedream instead, create an API key in the ModelArk AP region and set:
IMAGE_PROVIDER=seedream ARK_API_KEY=<your-api-key>
SeeUsing the BytePlus Seedream providerfor compatibility details.
[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"
[mcp_servers.mcp-image] command = "node" args = ["/absolute/path/to/mcp-image/dist/index.js"] [mcp_servers.mcp-image.env] IMAGE_PROVIDER = "openai" OPENAI_API_KEY = "your_openai_api_key_here" IMAGE_OUTPUT_DIR = "/absolute/path/to/images"
- Global(all projects):~/.cursor/mcp.json
- Project-specific:.cursor/mcp.jsonin your project root
{ "mcpServers": { "mcp-image": { "command": "npx", "args": ["-y", "mcp-image"], "env": { "GEMINI_API_KEY": "your_gemini_api_key_here", "IMAGE_OUTPUT_DIR": "/absolute/path/to/images" } } } }
{ "mcpServers": { "mcp-image": { "command": "node", "args": ["/absolute/path/to/mcp-image/dist/index.js"], "env": { "IMAGE_PROVIDER": "openai", "OPENAI_API_KEY": "your_openai_api_key_here", "IMAGE_OUTPUT_DIR": "/absolute/path/to/images" } } } }
Run in your project directory to enable for that project:
cd /path/to/your/project claude mcp add mcp-image --env GEMINI_API_KEY=your-api-key --env IMAGE_OUTPUT_DIR=/absolute/path/to/images -- npx -y mcp-image
claude mcp add mcp-image --scope user --env GEMINI_API_KEY=your-api-key --env IMAGE_OUTPUT_DIR=/absolute/path/to/images -- npx -y mcp-image
npm install npm run build claude mcp add mcp-image --scope user \ --env IMAGE_PROVIDER=openai \ --env OPENAI_API_KEY=your-openai-api-key \ --env IMAGE_OUTPUT_DIR=/absolute/path/to/images \ -- node /absolute/path/to/mcp-image/dist/index.js
Security:Never commit API keys to version control. Use environment-specific configuration.
- IMAGE_OUTPUT_DIRmust be an absolute path (e.g.,/Users/username/images, not./images)
- Defaults to./outputin the current working directory if not specified
- Directory will be created automatically if it doesn't exist
The presets trade off speed, quality, and cost:
Set the default viaIMAGE_QUALITYenvironment variable:
IMAGE_QUALITY=fast # (default) Fastest generation IMAGE_QUALITY=balanced # Enhanced thinking for better quality IMAGE_QUALITY=quality # Maximum quality output
To override the preset for one request, tell your AI assistant to "generate in high quality" or "use balanced quality." The assistant passes the correspondingqualityparameter.
[mcp_servers.mcp-image.env] GEMINI_API_KEY = "your_gemini_api_key_here" IMAGE_QUALITY = "balanced"
Cursor:Add"IMAGE_QUALITY": "balanced"to the env section in your config.
claude mcp add mcp-image --env GEMINI_API_KEY=your-api-key --env IMAGE_QUALITY=balanced --env IMAGE_OUTPUT_DIR=/absolute/path/to/images -- npx -y mcp-image
SetSKIP_PROMPT_ENHANCEMENT=trueto send prompts directly to the image generator. Use this when the exact prompt wording needs to remain unchanged.
As of July 29, 2026, Seedream 5.0 Pro is available only in ModelArk AP (ap-southeast-1). Create an API key in theModelArk AP region console.
mcp-image usesseed-2-0-lite-260428for prompt enhancement and Seedream 5.0 Pro for image generation. These model choices are fixed by the server and are not configurable through environment variables.
All supported aspect ratios use BytePlus Method 1, so final pixel dimensions are model-selected. Seedream rejectsimageSize: "4K"anduseGoogleSearch: true. Image requests have a fixed 300-second timeout. Seedream image editing accepts PNG and JPEG input images only.
SetIMAGE_PROVIDER=openaito use OpenAI for both prompt enhancement and image generation. mcp-image currently usesgpt-5.4-nanofor prompt enhancement andgpt-image-2for image generation. These model choices are fixed by the server and are not configurable through environment variables.
OpenAI may require organization verification before allowing access togpt-image-2. If image generation fails with a 403 permission or verification error, check your organization settings:https://platform.openai.com/settings/organization/general
- Supports text-to-image and image-to-image generation.
- SupportsaspectRatio, mapped to the closest supported OpenAI image size.
- SupportsimageSizevalues1K,2K, and4K.
- Mapsqualityasfast -> low,balanced -> medium, andquality -> high. For anything beyond simple subjects,balancedorqualityis recommended.
- Does not supportuseGoogleSearch; that option is only available with the Gemini provider.
Prompt enhancement uses a separate OpenAI Responses API call. SetSKIP_PROMPT_ENHANCEMENT=trueto send prompts directly to the image model.
Once configured, describe the image in natural language:
"Generate a serene mountain landscape at sunset with a lake reflection"
Prompt enhancement fills in relevant details about lighting, materials, composition, and atmosphere.
"Edit this image to make the person face right" (with inputImagePath: "/path/to/image.jpg")
"Generate a portrait of a medieval knight, maintaining character consistency for future variations" (with maintainCharacterConsistency: true)
"Generate a professional product photo of a smartphone with clear text on the screen" (with imageSize: "4K")
"Generate a cinematic landscape of a desert at golden hour" (with aspectRatio: "21:9")
The server uses a separate model for each of its two stages:
- Prompt Optimization(Gemini 2.5 Flash by default,gpt-5.4-nanovia OpenAI Responses in OpenAI mode, orseed-2-0-lite-260428via ModelArk Responses in Seedream mode): Refines your prompt using the Subject–Context–Style framework. Skippable viaSKIP_PROMPT_ENHANCEMENT.
- Image Generation(Nano Banana 2/Pro by default,gpt-image-2in OpenAI mode, or Seedream 5.0 Pro in Seedream mode): Creates the final image. Provider-specific quality mappings are described above.
{ "type": "resource", "resource": { "uri": "file:///path/to/generated/image.png", "name": "image-filename.png", "mimeType": "image/png" }, "metadata": { "model": "gemini-3.1-flash-image", "provider": "gemini", "processingTime": 5000, "timestamp": "2026-01-01T12:00:00.000Z" } }
- EnsureGEMINI_API_KEYis set when using Gemini,OPENAI_API_KEYis set whenIMAGE_PROVIDER=openai, orARK_API_KEYis set whenIMAGE_PROVIDER=seedream
- Verify the API key is valid and has image generation permissions
- Use absolute file paths, not relative paths
- Ensure the file exists and is accessible
- Supported formats: PNG, JPEG, WebP (max 10MB)
"No image data found in Gemini API response"
- Try rephrasing your prompt with more specific details
- Ensure your prompt is appropriate for image generation
- Check if your API key has sufficient quota
- In Gemini mode, thefastpreset typically takes ~30–40 seconds including prompt optimization
- In Gemini mode,balanceduses additional thinking andqualityselects Nano Banana Pro
- In Seedream mode, use the route table above; all tiers use Pro, withfastselecting nativefastoptimization andbalanced/qualityselectingstandard
- High-resolution (2K/4K): Processing time varies by provider and route
- Say what the image is for; the optimizer supplies the photographic terms it implies
- Details you specify yourself are carried through rather than rewritten
- ConsideruseWorldKnowledgefor historical or factual subjects
- UseimageSize: "4K"when the selected provider supports it; Seedream accepts1Kand2K
- This MCP server uses the paid Gemini API:
- Prompt optimization: Gemini 2.5 Flash (minimal token usage)
- Image generation: Model depends on quality preset
- fast/balanced: Nano Banana 2 (Gemini 3.1 Flash Image, lower cost)
- quality: Nano Banana Pro (Gemini 3 Pro Image, higher cost)
Standalone Agent Skill: Image Generation Prompt Guide
This project also includes a standaloneAgent Skill(SKILL.md). Use it to help an AI assistant write prompts for a tool that already supports image generation. The skill is separate from the MCP server, does not call it, and does not require an API key.
The skill covers theSubject-Context-Styleframework, lighting, textures, camera angles, character consistency, composition, and image editing. It works with Gemini, GPT Image, Flux, Stable Diffusion, Midjourney, and other image models.
npx mcp-image skills install --path <skills-directory>
The skill will be placed at<skills-directory>/image-generation/SKILL.md. For example:~/.cursor/skills(Cursor),~/.codex/skills(Codex), or~/.claude/skills(Claude Code).
Need help?Open an issueor check thetroubleshooting sectionabove.
An MCP server for AI video generation. MCP server for AI video generation. Lets Claude, ChatGPT, OpenClaw , Hermes & other agents create AI videos and publish them to YouTube, TikTok, Instagram etc..
All-in-one AI creative studio — generate videos, images, audio in 11 Indian languages, and 3D models via MCP. Hosted at mcp.arcframe.ai.
Hosted MCP server for AudioPod's audio AI: text-to-speech, voice cloning, music generation, stem and speaker separation, transcription, denoise, and voice conversion.
Official MCP server for Comfy Cloud - generate images, video, audio, and 3D, run ComfyUI workflows, and search models directly from Claude and other AI agents
Generate images using Replicate's Flux Schnell model.
A server for creating fast and free lipsync videos for digital avatars, supporting both realistic and cartoon styles.
Pay-per-call AI API marketplace with 47 endpoints — OCR, LLM chat, image-gen, TTS
AI virtual staging for real estate — stage rooms, beautify floor plans, classify images, generate property descriptions
MachineTranslation.com MCP provides AI-powered multilingual translation through the Model Context Protocol. It uses multi-model consensus to deliver high-confidence translations and can be connected to AI assistants such as Claude, ChatGPT, Cursor, and other MCP-compatible clients.
Licensed AI content access. 1,821 Dhar Mann Studios videos. $0.0025/pull, creator compensated automatically. 30ms delivery.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
