MCP Image

MCP图像生成器🍌

用于Cursor、Claude Code、Codex和任何MCP兼容工具的AI图像生成和编辑MCP服务器，由Nano Banana 2和Nano Banana Pro（Google Gemini）提供支持，并可选择OpenAI GPT图像支持。

](https://www.npmjs.com/package/mcp-image) ](https://www.npmjs.com/package/mcp-image) 

将简单的文本提示转换为高质量图像的MCP服务器。与简单的API包装器不同，该服务器自动增强提示并配置生成的合理默认值-您不需要学习提示工程或调整设置。描述一下你想要什么。

运作原理

You: "cat on a roof"
        ↓
  Your AI assistant infers context
  (purpose, style, mood, resolution...)
        ↓
  MCP optimizes your prompt
  (adds lighting, composition, atmosphere, artistic details)
        ↓
  Image generation with smart defaults
  (grounding, consistency, resolution — all configured automatically)
        ↓
  High-quality image, zero effort

你的人工智能助手会解释你的意图——你的请求背后的风格、目的和背景。MCP通过细化提示以满足结构化的视觉清晰度标准并选择适当的生成设置来关注输出质量。你只需描述你想要什么。

提示优化器使用 主题-背景-风格 框架（默认情况下由Gemini 2.5 Flash提供支持，或在以下情况下由OpenAI Responses提供支持 IMAGE_PROVIDER=openai)填补缺失的视觉细节——主体特征、环境、照明、摄影作品——同时保持你的初衷。它不会盲目地添加细节：已经符合质量标准的提示基本上保持不变。

示例——优化器对一个简短的提示做了什么：

输入： “屋顶上的猫” 优化后： “一只光滑的午夜黑猫，优雅地栖息在风化的赤陶瓦屋顶的顶端。它的祖母绿眼睛微微眯起，反射出夕阳的温暖光芒。每块瓷砖都很独特，颜色和质地都有微妙的变化，裂缝上还附着着几块苔藓。猫的皮毛轮廓分明，能捕捉到黄金时段的光线，突出其光滑的轮廓。在背景中，遥远的旧世界城市建筑的轮廓被柔和地模糊了，沐浴在火红的橙色、柔和的粉红色和深紫色的暮色中。一种柔和的、空灵的薄雾开始从下面的小巷升起，增添了一丝神秘感。构图是一种中等拍摄角度略低，强调了猫在广阔天空中的威严。用定焦镜头拍摄的照片级写实风格，大光圈营造出美丽的散景，增强了景深。”

特性

• 内置快速优化：您的简单提示会自动丰富摄影和艺术细节——照明、构图、氛围——默认情况下使用Gemini 2.5 Flash，或在以下情况下使用OpenAI Responses IMAGE_PROVIDER=openai不需要快速的工程技能。
• 可选OpenAI提供程序：设置 IMAGE_PROVIDER=openai 使用OpenAI GPT映像模型生成和编辑映像，例如 gpt-image-2.
• 三个质量等级：使用Nano Banana 2（Gemini 3.1 Flash Image）和Nano Banana Pro（Gemini 3 Pro Image）在快速迭代、平衡质量或最大保真度之间进行选择。 请参阅质量预设.
• 图像编辑：使用自然语言指令转换现有图像（图像到图像），同时保持原始风格和视觉一致性。
• 高分辨率输出：高达4K的图像生成，可实现专业级输出，具有卓越的文本渲染和精细的细节。
• 灵活的纵横比：从方形（1:1）到超宽（21:9）和超高（1:8）格式。
• 字符一致性：在多代人中保持一致的角色外观——非常适合故事板、产品镜头和视觉系列。
• 高性能:

- 谷歌搜索为实时事实准确性奠定了基础 - 历史人物、地标和事实场景的照片级真实感描绘的世界知识 - 合成场景的多图像混合 - 目标意识生成（例如，“食谱封面”产生的结果与“社交媒体帖子”不同）

• 多种输出格式：PNG、JPEG、WebP支持。

代理技能：图像生成提示指南

该项目还提供了一个独立的 代理技能 (SKILL.md)教人工智能助手编写更好的图像生成提示-不需要MCP服务器或API密钥。

注： 此技能本身不会生成图像。它教你的人工智能助手为已经内置图像生成的工具编写更好的提示（例如，Cursor的原生图像生成）。

基于 主题上下文风格 框架，涵盖提示结构、视觉细节（照明、纹理、相机角度）、高级技术（角色一致性、构图）和图像编辑。适用于任何图像模型（Gemini、GPT图像、Flux、稳定扩散、Midjourney等）。

安装

npx mcp-image skills install --path 

技能将被放置在 /image-generation/SKILL.md.指定AI工具的技能目录：

# Cursor
npx mcp-image skills install --path ~/.cursor/skills

# Codex
npx mcp-image skills install --path ~/.codex/skills

# Claude Code
npx mcp-image skills install --path ~/.claude/skills

何时使用技能与MCP服务器

______________________________________________________________________

先决条件

• Node.js 22或以上
• Gemini API密钥 -获取你的 谷歌AI工作室 对于默认的Gemini提供程序
• OpenAI API密钥 -从以下地址获取您的 开放人工智能 使用时 IMAGE_PROVIDER=openai
• 与MCP兼容的AI工具： 光标, 克劳德代码, 法典，或其他
• 基本的终端/命令行知识

快速开始

1.获取Gemini API密钥

从获取API密钥 谷歌AI工作室

要使用OpenAI，请获取OpenAI API密钥并设置：

IMAGE_PROVIDER=openai
OPENAI_API_KEY=your_openai_api_key_here

OpenAI模式需要组织验证——请参阅 使用OpenAI提供者 下面是设置细节和功能差异。

2.MCP配置

食品法典委员会

添加 ~/.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"

对于来自本地分支的OpenAI GPT映像：

[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"

对于光标

添加到光标设置中：

• 全球 （所有项目）： ~/.cursor/mcp.json
• 项目特定: .cursor/mcp.json 在项目根目录中

{
  "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"
      }
    }
  }
}

对于来自本地分支的OpenAI GPT映像：

{
  "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"
      }
    }
  }
}

克劳德代码

在项目目录中运行以启用该项目：

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

对于来自本地分支的OpenAI GPT映像：

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

⚠️ 安全说明：永远不要将API密钥提交给版本控制。保持安全，并使用特定于环境的配置。

📁 路径要求:

• IMAGE_OUTPUT_DIR 必须是绝对路径（例如。， /Users/username/images，不 ./images)
• 默认为 ./output 如果未指定，则在当前工作目录中
• 如果目录不存在，将自动创建

质量预设

选择速度、质量和成本之间的正确平衡：

通过设置默认值 IMAGE_QUALITY 环境变量：

IMAGE_QUALITY=fast       # (default) Fastest generation
IMAGE_QUALITY=balanced   # Enhanced thinking for better quality
IMAGE_QUALITY=quality    # Maximum quality output

要覆盖每个请求，只需告诉你的人工智能助手（例如，“高质量生成”或“使用平衡质量”）。助理将通过适当的 quality 参数自动。

食品法典：

[mcp_servers.mcp-image.env]
GEMINI_API_KEY = "your_gemini_api_key_here"
IMAGE_QUALITY = "balanced"

光标： 添加 "IMAGE_QUALITY": "balanced" 转到配置中的env部分。

克劳德代码：

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

跳过提示增强

集 SKIP_PROMPT_ENHANCEMENT=true 禁用自动提示优化，并将提示直接发送到图像生成器。当您需要完全控制确切的提示措辞时很有用。

提供者配置

使用OpenAI提供者

集 IMAGE_PROVIDER=openai 使用OpenAI进行即时增强和图像生成。mcp映像当前使用 gpt-4o-mini 为了迅速增强和 gpt-image-2 用于图像生成。这些模型选择由服务器固定，不能通过环境变量进行配置。

OpenAI在允许访问之前可能需要组织验证 gpt-image-2。如果图像生成失败，出现403权限或验证错误，请检查您的组织设置：https://platform.openai.com/settings/organization/general

OpenAI提供者行为：

• 支持文本到图像和图像到图像的生成。
• 支持 aspectRatio，映射到最接近支持的OpenAI图像大小。
• 支持 imageSize 价值观 1K, 2K，以及 4K.
• 地图 quality 作为 fast -> low, balanced -> medium，以及 quality -> high.
• 不支持 useGoogleSearch；该选项仅适用于Gemini提供商。

提示增强使用单独的OpenAI响应API调用。集 SKIP_PROMPT_ENHANCEMENT=true 直接向图像模型发送提示。

用法示例

配置后，只需用自然语言描述您想要的内容：

基本图像生成

"Generate a serene mountain landscape at sunset with a lake reflection"

您的提示会自动增强，包含有关照明、材质、构图和氛围的丰富细节。

图像编辑

"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)

高分辨率4K文本渲染：

"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")

API 参考

generate_image 工具

服务器使用两阶段流程，每个阶段都有单独的模型：

1. 快速优化 （默认情况下为Gemini 2.5 Flash，或 gpt-4o-mini 通过OpenAI模式下的OpenAI响应）：使用主题-上下文-样式框架优化您的提示。可通过跳过 SKIP_PROMPT_ENHANCEMENT.
2. 图像生成 （默认情况下为Nano Banana 2/Pro，或 gpt-image-2 在OpenAI模式下）：创建最终图像。在Gemini模式下，模型会根据预设的质量而变化；在OpenAI模式下，模型被固定 quality 地图到OpenAI low/medium/high.

参数

回应

{
  "type": "resource",
  "resource": {
    "uri": "file:///path/to/generated/image.png",
    "name": "image-filename.png",
    "mimeType": "image/png"
  },
  "metadata": {
    "model": "gemini-3.1-flash-image-preview",
    "provider": "gemini",
    "processingTime": 5000,
    "timestamp": "2026-01-01T12:00:00.000Z"
  }
}

故障排除

常见问题

“找不到API密钥”

• 确保 GEMINI_API_KEY 使用Gemini时设置，或 OPENAI_API_KEY 设置时间为 IMAGE_PROVIDER=openai
• 验证API密钥是否有效并具有图像生成权限

“找不到输入图像文件”

• 使用绝对文件路径，而不是相对路径
• 确保文件存在并且可访问
• 支持的格式：PNG、JPEG、WebP（最大10MB）

“在Gemini API响应中找不到图像数据”

• 试着用更具体的细节重新表述你的提示
• 确保您的提示适合生成图像
• 检查您的API密钥是否有足够的配额

性能提示

• fast 预设：约30-40秒典型值（包括提示优化）
• balanced 预设：由于思维增强，长度稍长
• quality 预设：输出速度较慢但保真度最高
• 高分辨率（2K/4K）：额外的处理时间可获得卓越的细节
• 简单的提示效果很好——优化器会自动添加专业细节
• 保留并进一步增强了复杂的提示
• 考虑 useWorldKnowledge 历史或事实主题
• 使用 imageSize: "4K" 当文本清晰度和细节至关重要时

使用说明

• 此MCP服务器使用付费的Gemini API：

- 快速优化：Gemini 2.5 Flash（最低代币使用量） - 图像生成：型号取决于预设的质量 - fast / balanced：Nano Banana 2-Gemini 3.1闪光图像（成本更低） - quality：Nano Banana Pro-Gemini 3 Pro图像（成本较高） - balanced 使用额外的思维令牌（成本略高于 fast)

• 查看当前定价和费率限制 谷歌AI工作室
• 监控您的API使用情况以避免意外收费
• 快速优化步骤增加了最小的成本，同时显著提高了输出质量

许可证

MIT许可证-请参阅 许可证 了解详情。

______________________________________________________________________