MCP Image MCP — Use Cases, Install & Live Demo

Why use it

Key features

One tool: generate_image (covers gen + edit)
Automatic prompt enhancement (Subject · Context · Style)
Three quality tiers: fast, balanced, quality
4K resolution; aspect ratios 1:1 through 21:9
Character consistency across calls
Google Search grounding + world knowledge

Live Demo

What it looks like in practice

mcp-image.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-image": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-image"
      ],
      "env": {
        "GEMINI_API_KEY": "<from aistudio.google.com/apikey>",
        "IMAGE_OUTPUT_DIR": "/absolute/path/to/images"
      }
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-image": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-image"
      ],
      "env": {
        "GEMINI_API_KEY": "<from aistudio.google.com/apikey>",
        "IMAGE_OUTPUT_DIR": "/absolute/path/to/images"
      }
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-image": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-image"
      ],
      "env": {
        "GEMINI_API_KEY": "<from aistudio.google.com/apikey>",
        "IMAGE_OUTPUT_DIR": "/absolute/path/to/images"
      }
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-image": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-image"
      ],
      "env": {
        "GEMINI_API_KEY": "<from aistudio.google.com/apikey>",
        "IMAGE_OUTPUT_DIR": "/absolute/path/to/images"
      }
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-image",
      "command": "npx",
      "args": [
        "-y",
        "mcp-image"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-image": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mcp-image"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add mcp-image -- npx -y mcp-image

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use MCP Image

Generate then iterate a hero image for a landing page

👤 Designers, founders, marketers ⏱ ~15 min beginner

When to use: You want a fresh hero image and don't want to juggle 5 tabs.

Prerequisites

Gemini API key — https://aistudio.google.com/apikey
Output directory — mkdir -p ~/images/mcp

Flow

Generate v1

Generate a hero image: minimal workspace, warm golden-hour light, 16:9, quality tier, 2048px.✓ Copied

→ Image saved to IMAGE_OUTPUT_DIR with enriched prompt echoed back
Edit in place

Edit it — add a thin line of trees on the horizon, keep everything else.✓ Copied

→ Variant saved; composition preserved
Try a variant

Same scene but cooler tones, keep the subject identical.✓ Copied

→ Character consistency holds; color shifted

Outcome: A shippable hero image in minutes, not a paid-seat round-trip through Midjourney.

Pitfalls

Over-prompting the optimizer — Let the Subject-Context-Style enhancer do its job; stop overriding with 5 lines of adjectives

Combine with: filesystem

Produce a set of brand-consistent illustrations

👤 Solo founders and designers without a brand-asset library ⏱ ~45 min intermediate

When to use: You need 6–12 illustrations that look like they belong together.

Flow

Define the style sheet

Generate a style reference: flat illustration, soft pastel palette, 2-character vignette.✓ Copied

→ Seed image captures the style
Create variations

Using that style, make 6 illustrations for our sections: onboarding, billing, team, integrations, security, analytics.✓ Copied

→ 6 images with consistent style + characters

Outcome: A cohesive illustration set without hiring an illustrator for one day.

Pitfalls

Drift between images — Always reference the seed image and use 'keep style from seed'

Edit product photos with natural language

👤 E-commerce operators, small brands ⏱ ~20 min beginner

When to use: You have a raw product photo and want the hero treatment without Photoshop.

Flow

Upload / reference the photo

Use product.jpg as base. Remove the cluttered background; keep shadow; studio lighting.✓ Copied

→ Clean product shot with natural shadow
Add context

Same product on a warm marble surface, top-down.✓ Copied

→ Consistent product with new environment

Outcome: Catalog-ready imagery in minutes.

Combine with: filesystem

Combinations

Pair with other MCPs for X10 leverage

mcp-image + filesystem

Generate, list, tag, and organize an image library

Generate today's set into ~/images/mcp/2026-04-21/; then list and rename by alt-text.✓ Copied

mcp-image + magic-ui-mcp

Drop generated hero images into a Magic UI landing

Generate a hero image, then wire it into the Magic UI hero component.✓ Copied

mcp-image + comfyui-mcp-server

Use mcp-image for one-off generations; ComfyUI for pipelines

Quick variants via mcp-image; production workflow via ComfyUI.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
generate_image	prompt: str, tier?: fast\|balanced\|quality, aspect?: '1:1'\|'16:9'\|..., base_image?: path, size?: '1K'\|'2K'\|'4K'	Generate a fresh image or edit an existing one with natural language	1 Gemini image call

Cost & Limits

What this costs to run

API quota: Bound by your Gemini API plan's image-generation quota
Tokens per call: Negligible for text; image bytes dominate
Monetary: Pay-per-image via Gemini API; free tier available for development
Tip: Use tier=fast for iteration and tier=quality only for the final keeper.

Security

Permissions, secrets, blast radius

Credential storage: GEMINI_API_KEY in env only — never commit. Rotate from Google AI Studio if leaked.

Data egress: Prompts and optional base images go to Google's Gemini API. Generated bytes return and are saved locally.

Google's policies apply to generated images. Don't generate content you don't have rights to share.
Base images you pass for edits are uploaded to Gemini — treat them as if you posted them to the internet.

Troubleshooting

Common errors and fixes

401 / API key invalid

Confirm GEMINI_API_KEY is the raw API key from AI Studio (not OAuth token), and has image-generation enabled.

Verify: curl https://generativelanguage.googleapis.com/v1beta/models?key=$GEMINI_API_KEY

Outputs saved but empty

IMAGE_OUTPUT_DIR might be non-writable or missing. Create it and retry.

Verify: touch $IMAGE_OUTPUT_DIR/.probe && rm $IMAGE_OUTPUT_DIR/.probe

Character drifts between generations

Always pass the same base_image and include 'keep subject identical' in the prompt.

Verify: Diff two generations visually

Alternatives

MCP Image vs others

Alternative	When to use it instead	Tradeoff
everart	You have style-trained Everart models	Different provider, different style coverage
comfyui-mcp-server	You need custom SD/FLUX workflows and full pipeline control	Much heavier setup
higgsfield-ai-prompt-skill	You want prompt engineering help for another provider	Prompts only — no inference

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills