Generate Images With Claude Using MCP (2026)

Claude can generate raster images when an MCP server exposes an image model as a tool. Claude writes the prompt from your project context, calls the tool, receives a saved file path, and can place the selected asset into the codebase without leaving the coding session.

This is the implementation guide: install a local server, connect it to Claude Code, use a current provider model, generate and edit files, and debug the connection. If you only need the capability answer and a comparison with native ChatGPT or Gemini image generation, read Can Claude Generate Images? first.

How Claude Generates Images Through MCP

Claude generates an image through MCP by calling agenerate_image tool on a connected server. The server converts that tool call into a request to Gemini or OpenAI, saves the returned image locally, and sends the path and metadata back to Claude.

Your request
  -> Claude Code
      -> MCP client
          -> image generation MCP server
              -> Gemini or OpenAI image API
          <- saved image path
      <- preview, move, or edit the asset

Claude itself still produces text and tool calls, not pixels. The model behind the MCP server produces the pixels. That boundary is why you can swap providers without changing how you ask Claude for an asset, and it is the same separation explained in MCP vs API.

What You Need Before Starting

You need Claude Code, Git, Node.js, pnpm, and a funded image-provider API key. The local server is free and open source, but provider requests can incur usage charges.

• A working Claude Code installation. Use the OS-specific setup guide if claude --version fails.
• Git and a current Node.js runtime.
• pnpm for installing and building the server.
• An OpenAI API key for GPT Image 2, or a Gemini API key for a model the server currently supports.
• An absolute directory where generated images may be written.

A Claude Pro or Max subscription does not pay the outside image provider. Claude Code usage and image API usage are billed separately, so set provider spend limits before testing an automated loop.

Choose a Hosted or Local MCP Server

Choose a hosted server when you want a quick connection and managed output checks. Choose a local server when you want source access, provider control, local file paths, and the ability to modify the tool schema.

The walkthrough below uses my open-source Image Generation MCP Server over local stdio. It exposes one image tool, supports text-to-image and reference-image editing, and returns a local file path Claude Code can use immediately.

Install the Image Generation MCP Server

Clone the repository, install its dependencies, and build the JavaScript entry point. Keep the resulting directory in a stable location because Claude Code will store its absolute path.

git clone https://github.com/Legorobotdude/mcp-image-gen.git
cd mcp-image-gen
pnpm install
pnpm build
pwd

Copy the absolute path printed by pwd. The server entry point is dist/index.js inside that directory. Review the current repository README and source before running updates because model IDs, accepted arguments, and provider behavior can change independently of Claude Code.

Choose a Current Image Model

Use GPT Image 2 for the most direct current path through this server. The repository accepts gpt-image-2, and OpenAI lists that ID as its current state-of-the-art image generation and editing model.

Be careful with copied Gemini examples. Google shut downgemini-3.1-flash-image-preview andgemini-3-pro-image-preview on June 25, 2026. Their current stable replacements are gemini-3.1-flash-image andgemini-3-pro-image. Confirm that the MCP server version you install accepts those stable IDs before selecting them.

Verify live model names in Google's image generation documentation or the GPT Image 2 model page. My AI model API ID reference covers the same versioning problem across providers.

Connect the Server to Claude Code

Add the built server as a user-scoped stdio connection and pass only the provider key you need. User scope makes the tool available across local projects without committing the key or a machine-specific path.

On macOS or Linux, read the key without echoing it into the terminal, substitute the absolute server path, and add the connection:

read -s OPENAI_API_KEY
claude mcp add --scope user   --env OPENAI_API_KEY="$OPENAI_API_KEY"   --transport stdio mcp-image-gen   -- node "/absolute/path/to/mcp-image-gen/dist/index.js"
unset OPENAI_API_KEY

The -- separator is required. Options before it configure Claude Code; everything after it is the command used to start the server. Anthropic documents that ordering in the official Claude Code MCP setup guide.

For a team-shared connection, use a project.mcp.json with environment-variable expansion instead of embedding the key. Commit the server contract only after every teammate can supply the secret through their own environment.

Verify the MCP Connection

Verify the server outside and inside a Claude session before generating anything. A healthy connection appears in the CLI list and exposes agenerate_image tool in the /mcp panel.

claude mcp list
claude mcp get mcp-image-gen
claude

Inside Claude Code, run /mcp. If the server is disconnected, inspect the command and absolute path. If it is connected but exposes no tools, rebuild the repository and restart Claude Code. You can also use my MCP inspector for compatible remote servers, but local stdio servers are easiest to inspect from the host that launches them.

Generate Your First Image

Ask Claude to call the tool with an explicit model, aspect ratio, and size. Naming the model avoids an outdated server default and makes the result reproducible.

Use the mcp-image-gen generate_image tool.

Create a 16:9 editorial illustration of an AI coding agent
connecting to tools through a clean node graph. Dark navy
background, restrained cyan accents, no logos, no text.

Use model gpt-image-2 and imageSize large.
Return the saved file path when complete.

The tool response includes the saved path, selected provider, model, prompt, aspect ratio, and size. Open the file and inspect it before asking Claude to modify your project. Generated text, hands, faces, and product details still deserve a human review.

Generate an Image Into a Project

Give Claude the destination, dimensions, visual role, and acceptance checks so generation becomes one step in a real implementation rather than an isolated prompt.

Create a hero image for this Next.js project.

1. Read the homepage copy and existing color tokens.
2. Generate three 16:9 options with gpt-image-2.
3. Show me the file paths and a one-line visual difference for each.
4. Wait for my selection.
5. Copy only the selected image to public/images/product-hero.png.
6. Add it with accurate alt text and preserve the existing layout.
7. Run the relevant lint and build checks.

The approval pause matters. Generation is nondeterministic, and automatically replacing an asset before review can create noisy diffs or ship a visually wrong result. Keep source generation outside the repo, then copy only the accepted file into version control.

Edit an Existing Image With Claude

Edit an image by passing an absolute source path to the MCP tool and describing what must change and what must remain fixed. The server supports PNG, JPEG, and WebP inputs for both provider paths.

Use generate_image with this source image:
/absolute/path/to/product-photo.png

Remove the background and replace it with a warm light-gray studio
surface. Preserve the product shape, color, labels, and camera angle.
Use model gpt-image-2, a 4:3 aspect ratio, and large size.
Save a new file. Do not overwrite the source.

Use one or two strong reference images before trying a large batch. More inputs can improve character or product consistency, but they also increase cost and make it harder to tell which reference caused a bad result.

Protect API Keys and Source Images

Treat the MCP server as third-party code with access to the provider key and every source image you pass. Keep its permissions narrow, inspect updates, and never commit secrets to a shared MCP configuration.

• Use a provider project with a spend cap and a key dedicated to image generation.
• Store local credentials at user scope, not in the repository.
• Pass only the files needed for one edit, using explicit absolute paths.
• Review the server's dependency and source changes before pulling an update.
• Do not send confidential customer or biometric images unless the provider's data controls meet your requirements.

MCP standardizes the connection, not trust. The MCP server security section explains why local execution, remote authorization, and host approvals need separate review.

Fix Common MCP Image Errors

Most failures come from a stale model ID, missing provider key, wrong absolute path, unbuilt server, or unwritable output directory. Check them in that order.

Run claude mcp get mcp-image-gen after any config change. Remove and re-add a bad entry instead of maintaining duplicate servers with slightly different names.

Can You Generate Images for Free?

The local MCP server is free under the MIT license, but current image APIs are metered and may require billing before the first request. Provider trials and quotas can change, so treat free usage as temporary rather than an architecture.

If you need one image without installing a server, use the browser-based AI image generator. Use MCP when the valuable part is the workflow: Claude reads the project, writes a context-aware prompt, generates variations, waits for selection, and integrates the chosen asset with the code.