mcp-image

MCP 图像生成器 🍌

可从 Codex、Cursor、Claude Code 或任何 MCP 客户端生成和编辑图像。mcp-image 会在将请求发送给 Gemini、OpenAI 或 BytePlus Seedream 之前，为请求补充视觉指导。

告诉它要创建什么图像，或要如何修改现有图像，以及图像的用途。结果会保存到磁盘，并返回给你的助手。

功能介绍

生成图像前，mcp-image 会将简短请求改写为更具体的提示词。它会保留你的要求，并补充构图、光线和拍摄角度等细节。你提供的细节越多，它改动的内容就越少。

你的请求：

“一张烤鸡晚餐的照片，用于食谱网站。看起来要像是实际烹制出来的，而且要呈现出切到一半的状态，让人看得出肉汁有多丰富。”

mcp-image 发送给图像模型的内容：

“……一只刚烤好的整鸡，放在质朴、带有使用痕迹的木质砧板上。鸡皮呈现深棕色、带有焦斑且酥脆的状态……鸡肉已切到一半，一侧鸡胸肉被整齐切开，露出鲜嫩、冒着热气的白肉，天然肉汁闪闪发亮，并微微淌到砧板上……背景柔和虚化，呈现浅景深效果。”

使用 Gemini 和默认的 fast 质量预设生成。

保留了以下要求：

• 用于食谱网站：突出一个明确的主体，让其他内容都处于次要位置
• 实际烹制出来：呈现焦斑、不均匀的棕色、升腾的蒸汽，以及刀上的肉汁
• 切到一半的状态：一侧鸡胸肉被切开，切下的肉仍靠在鸡身上
• 肉汁有多丰富：肉汁淌在砧板上，切口周围采用浅景深效果

对比关闭提示词增强后的相同请求

使用相同请求生成的基准图像，已禁用提示词增强。

设置 SKIP_PROMPT_ENHANCEMENT=true，即可将原始提示词原样发送给图像模型。

快速开始

你需要 Node.js 22 或更高版本、兼容 MCP 的客户端，以及任一图像提供商的 API 密钥。

1. 获取 API 密钥

这三家提供商都支持生成和编辑图像。Gemini 是默认选项，所需配置最少。

只有 Gemini 支持 Google Search grounding。OpenAI 可能要求先完成组织验证，才能生成图像。

以下示例使用 Gemini。如果你更喜欢 OpenAI 或 Seedream，请替换提供商设置。

2. 配置 MCP 客户端

Codex

将以下内容添加到 ~/.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"

Cursor

若要用于所有项目，请将以下内容添加到 ~/.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"
      }
    }
  }
}

Claude Code

在你的项目目录中运行：

claude mcp add mcp-image --env GEMINI_API_KEY=your-api-key --env IMAGE_OUTPUT_DIR=/absolute/path/to/images -- npx -y mcp-image

在 mcp-image 后添加 --scope user，即可在每个项目中使用。

切勿将 API 密钥提交到版本控制中。请在 MCP 配置中使用绝对路径设置 IMAGE_OUTPUT_DIR，因为服务的工作目录取决于客户端。如果省略此项，图像将写入相对于该工作目录的 ./output。

3. 生成图像

更改配置后，重启 MCP 客户端，然后向 AI 助手提出请求：

Generate a product photo of a ceramic coffee mug on a wooden desk.

生成的文件会保存到配置的输出目录，并作为 MCP 资源返回给助手。

pnpm install
pnpm run build

node /absolute/path/to/mcp-image/dist/index.js

更多示例

编辑现有图像

向助手提供源图像的绝对路径：

Edit /path/to/image.jpg so the person is facing right.

控制生成结果

• Generate a high-quality product photo of a smartphone with clear text on the screen.
• Generate a cinematic desert landscape in a 21:9 aspect ratio.
• Keep the knight's appearance consistent with the previous image.

请参阅工具参考，了解助手可以显式传入的选项。

配置

更改提供方会同时影响提示词增强和图像生成。请求生成图像的方式保持不变。

质量

IMAGE_QUALITY 接受 fast（默认值）、balanced 或 quality。在 MCP 服务环境中设置：

IMAGE_QUALITY=balanced

使用 fast 快速尝试创意，日常使用可选 balanced，复杂场景或注重细节的图像可选 quality。较高的设置可能需要更长时间且成本更高；结果因提供方而异。

所有三个提供方都支持这些生成和编辑预设。你可以通过每次请求中的 quality 选项覆盖默认值。

环境变量

你可以配置多个提供方的密钥，并在每次请求中切换。请求级别的 provider 选项优先于 IMAGE_PROVIDER。

工具参考

MCP 客户端会为你调用此工具。需要查看选项或提供方限制时，请打开参考内容。

故障排除

未找到 API 密钥

检查所选提供方的密钥是否存在于 MCP 服务的环境中：

• Gemini：GEMINI_API_KEY
• OpenAI：OPENAI_API_KEY
• Seedream：ARK_API_KEY

更改配置后，请重启 MCP 客户端。

未找到输入图像文件

请使用绝对路径，并确保 MCP 服务可以读取这些文件。输入图像可以是 PNG、JPEG 或 WebP，且每个文件不得超过 10 MiB。Seedream 编辑仅接受 PNG 和 JPEG。

提供方拒绝请求

请检查提供方表格中请求的尺寸。useGoogleSearch 仅适用于 Gemini，Seedream 不支持 4K。对于 OpenAI 权限错误，请检查组织设置。对于配额或速率限制错误，请检查所选提供方账号。

图像生成提示词技能

此代码库还包含一个 Agent Skill，适用于已能使用图像生成工具的助手。它介绍了 mcp-image 所采用的提示词编写方法，可独立于此服务使用。

使用以下命令安装：

npx mcp-image skills install --path <skills-directory>

例如，可将 ~/.codex/skills、~/.cursor/skills 或 ~/.claude/skills 用作目标目录。

许可证

MIT License。详情请参阅 LICENSE。

需要帮助？提交问题或查看故障排除。