mcp-image — Claude Code MCP server: what it does, how to install
This MCP server creates or edits images through Gemini, OpenAI, or BytePlus Seedream, adding visual detail to short requests before generation.
claude mcp add --env IMAGE_PROVIDER=<IMAGE_PROVIDER> --env GEMINI_API_KEY=<GEMINI_API_KEY> --env OPENAI_API_KEY=<OPENAI_API_KEY> --env ARK_API_KEY=<ARK_API_KEY> --env IMAGE_OUTPUT_DIR=<IMAGE_OUTPUT_DIR> --transport stdio mcp-image -- npx -y mcp-imageWhat mcp-image does
mcp-image handles requests for new images as well as edits to existing files. It expands a brief instruction with visual specifics such as framing, lighting, and camera position, while keeping the requested subject intact. The resulting file is written to the configured directory and returned to the assistant through MCP.
The server works with Gemini, OpenAI, and BytePlus Seedream. Gemini supports 1K, 2K, and 4K output; OpenAI and Seedream can return PNG or JPEG files. Image quality is controlled with IMAGE_QUALITY, using fast, balanced, or quality; fast is the default. Set SKIP_PROMPT_ENHANCEMENT=true when the original wording should go to the image model unchanged.
Run it with Node.js 22 or newer, an MCP-compatible client, and credentials for the selected provider. Without a provider key, the server cannot generate or edit an image. An absolute IMAGE_OUTPUT_DIR is the safer configuration because each client can use a different working directory.
What it helps with
- generate an image from a written brief
- edit an existing file by absolute path
- add visual detail to a short image request
- write generated files to a chosen directory
- switch between supported image providers
Example prompts for the agent
- Create a product photo of a ceramic mug on a wooden desk and save it to the configured output directory.
- Edit
/path/to/image.jpgso the person faces right. - Generate a cinematic desert scene with a 21:9 aspect ratio.
How to install mcp-image
Platform CLI
claude mcp add --env IMAGE_PROVIDER=<IMAGE_PROVIDER> --env GEMINI_API_KEY=<GEMINI_API_KEY> --env OPENAI_API_KEY=<OPENAI_API_KEY> --env ARK_API_KEY=<ARK_API_KEY> --env IMAGE_OUTPUT_DIR=<IMAGE_OUTPUT_DIR> --transport stdio mcp-image -- npx -y mcp-imageReplace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
codex mcp add mcp-image --env IMAGE_PROVIDER=<IMAGE_PROVIDER> --env GEMINI_API_KEY=<GEMINI_API_KEY> --env OPENAI_API_KEY=<OPENAI_API_KEY> --env ARK_API_KEY=<ARK_API_KEY> --env IMAGE_OUTPUT_DIR=<IMAGE_OUTPUT_DIR> -- npx -y mcp-imageReplace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"mcpServers": {
"mcp-image": {
"command": "npx",
"args": [
"-y",
"mcp-image"
],
"env": {
"IMAGE_PROVIDER": "<IMAGE_PROVIDER>",
"GEMINI_API_KEY": "<GEMINI_API_KEY>",
"OPENAI_API_KEY": "<OPENAI_API_KEY>",
"ARK_API_KEY": "<ARK_API_KEY>",
"IMAGE_OUTPUT_DIR": "<IMAGE_OUTPUT_DIR>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"servers": {
"mcp-image": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-image"
],
"env": {
"IMAGE_PROVIDER": "<IMAGE_PROVIDER>",
"GEMINI_API_KEY": "<GEMINI_API_KEY>",
"OPENAI_API_KEY": "<OPENAI_API_KEY>",
"ARK_API_KEY": "<ARK_API_KEY>",
"IMAGE_OUTPUT_DIR": "<IMAGE_OUTPUT_DIR>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
gemini mcp add -e IMAGE_PROVIDER=<IMAGE_PROVIDER> -e GEMINI_API_KEY=<GEMINI_API_KEY> -e OPENAI_API_KEY=<OPENAI_API_KEY> -e ARK_API_KEY=<ARK_API_KEY> -e IMAGE_OUTPUT_DIR=<IMAGE_OUTPUT_DIR> mcp-image npx -y mcp-imageReplace <…> with your own values. 2 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-image
How do I install mcp-image in Claude Code?
Run `claude mcp add mcp-image -e GEMINI_API_KEY=<GEMINI_API_KEY> -e OPENAI_API_KEY=<OPENAI_API_KEY> -e ARK_API_KEY=<ARK_API_KEY> -- npx -y mcp-image`.
What does mcp-image do?
It generates new images and edits existing ones through MCP. Before sending the request to an image provider, it can expand the prompt with visual details, then saves the result and returns it to the assistant.
Which image providers work with mcp-image?
The server supports Gemini, OpenAI, and BytePlus Seedream. Each choice requires its matching API key and provider configuration.
