imgx

imgx-mcp

AI 图像生成与编辑 MCP 服务。可与 Claude Code、Gemini CLI、Cursor、Windsurf 及任何兼容 MCP 的工具配合使用。

从文本生成图像、根据文本指令编辑现有图像、迭代优化结果——全部在 AI 编码环境中完成。

imgx-mcp 的独特之处

• 无需设计提示词——AI Agent 会保留对话上下文并自动构建优化后的提示词。只需描述需求；Agent 会处理提示词结构、模型选择和平台专属尺寸
• 内置 24 种编辑技巧——氛围、构图、风格迁移、元素调整和流行风格等，打包为 Agent 可按需应用的 Skill
• 支持撤销和重做的会话管理——迭代编辑、回退到任意节点、从中分支，或在并行会话间切换——为图像提供版本控制

快速开始

将其添加到工具的 MCP 配置中（.mcp.json、settings.json 等）：

{
  "mcpServers": {
    "imgx": {
      "command": "npx",
      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": { "GEMINI_API_KEY": "your-key" }
    }
  }
}

就这么简单。现在，你的 AI Agent 可以生成和编辑图像了。

Windows：将 "command": "npx" 替换为 "command": "cmd"，并在 args 数组前加上 "/c"。

Skill（Claude Code）

对于 Claude Code 用户，imgx-mcp 内含 image-generation Skill——一个引导式提示词，可教 Claude 如何有效使用 MCP 工具。安装 Skill 后，输入 /image-generation 即可开始引导式工作流。

安装 Skill

从 npm 包或 GitHub 仓库将 Skill 目录复制到项目中：

# From npm (after npx has cached the package)
cp -r $(npm root -g)/imgx-mcp/skills .claude/skills

# Or from the GitHub repository
curl -sL https://raw.githubusercontent.com/somacoffeekyoto/imgx-mcp/main/skills/image-generation/SKILL.md \
  -o .claude/skills/image-generation/SKILL.md --create-dirs
curl -sL https://raw.githubusercontent.com/somacoffeekyoto/imgx-mcp/main/skills/image-generation/references/providers.md \
  -o .claude/skills/image-generation/references/providers.md --create-dirs

也可以手动放置 Skill 文件：

your-project/
  .mcp.json                              ← MCP server config (Quick start above)
  .claude/
    skills/
      image-generation/
        SKILL.md                         ← skill prompt
        references/
          providers.md                   ← provider reference

Skill 文件包含在 npm 包的 skills/ 目录中，也可在 GitHub 仓库中找到。

个人 Skill（适用于所有项目）：放入 ~/.claude/skills/image-generation/，而不是 .claude/skills/。

Claude Desktop

Claude Desktop 支持通过 ZIP 上传 Skill：

1. 从仓库下载 image-generation-skill.zip（或在 npm 包的 dist/ 目录中查找）
2. 在 Claude Desktop 中：Settings > Profile > Customize > Skills > Add Skill
3. 上传 ZIP

发布新版本后，重新下载并上传 ZIP 即可更新 Skill。

Skill 的作用

MCP 服务赋予 AI 生成和编辑图像的能力。Skill 则提供了如何熟练使用这些工具的知识，因此你无需学习提示词语法、模型规格或特定服务的参数。

• 自动构建提示词 — 只需说“我需要一张封面图”。AI 就会使用主体-情境-风格框架构建结构化提示词：展示什么、放在哪里、呈现什么样的效果
• 24 种编辑技巧 — 调整氛围、改变构图、操控元素、迁移风格。“让它更暖一些”或“增加景深”——AI 会为模型选择合适的指令
• 智能选择模型 — 从免费模型开始。只有当你的需求超出免费层级的能力时，才会建议升级到付费模型，并说明具体变化
• 根据平台选择尺寸 — “Twitter OGP”或“App Store 截图”——AI 会选择正确的宽高比和分辨率。涵盖社交媒体、OGP、应用商店、印刷品和博客平台
• 热门风格模板 — Ghibli、盒装动作人偶、3D 黏土、像素艺术、Q 版等。说出风格名称，AI 就会应用合适的提示词结构
• 多图一致性 — 设计标记和角色 DNA 模板可在幻灯片、社交媒体系列和品牌素材中保持视觉统一

图像生成模型本身就具备这些能力。Skill 让你无需专业知识也能使用这些能力。

MCP 服务与 Skill

	MCP 服务	Skill
作用	向 AI Agent 提供图像工具	为如何使用这些工具提供引导式提示词
适用对象	任何兼容 MCP 的工具	Claude Code、Claude Desktop
安装	添加到 .mcp.json	将 skill 文件复制到项目中
团队共享	将 .mcp.json 提交到仓库	将 .claude/skills/ 提交到仓库

建议：设置 MCP 服务（快速入门）；如果你使用 Claude Code，则安装 Skill。

MCP 工具

工具	说明
generate_image	根据文本提示词生成图像
edit_image	根据文本指令编辑现有图像
edit_last	编辑上次生成或编辑的图像（无需提供输入路径）
undo_edit	撤销上次编辑，恢复会话中的上一张图像
redo_edit	重做之前撤销的编辑
edit_history	显示所有会话及其编辑历史和元数据
switch_session	切换到其他编辑会话
clear_history	清除项目历史记录（可选择删除图像文件）
set_output_dir	更改默认输出目录（可选择移动现有文件）
list_providers	列出可用的提供方及其功能

.imgx/ 目录用于存储编辑历史记录和默认图像输出。其位置取决于项目根目录检测结果：

项目根目录	.imgx/ 位置	历史记录
已检测到	<project-root>/.imgx/	<project-root>/.imgx/output-history.json
未检测到	~/Pictures/imgx/（仅图像）	~/.config/imgx/output-history.json（全局）

解析到同一项目根目录的所有客户端共享相同的历史记录。每个会话都有自己的子目录。响应中会返回文件路径。MCP 响应中包含图像内联预览（base64）。

迭代编辑

edit_last 工具会将上一次 generate_image 或 edit_image 调用的输出作为输入。这使对话式工作流成为可能：

"Generate a coffee shop interior" → generate_image
"Make the lighting warmer"        → edit_last
"Add a person reading a book"     → edit_last

各步骤之间无需指定文件路径。

会话管理

每次调用 generate_image 都会启动一个新会话。后续的 edit_last 调用会添加到同一会话中，形成编辑链。每个会话都有自己的输出目录。

撤销 / 重做 — 在编辑链中向后或向前移动：

generate → edit_last → edit_last → edit_last
                                    ↑ current
                       ← undo_edit
                       ↑ current
                            redo_edit →
                                    ↑ current

撤销后，调用 edit_last 会从当前位置创建分支（已放弃的条目及其文件会从磁盘中删除）。

文件命名 — edit_last 会根据源文件生成连续编号的文件名：

generate_image             → cover.png
edit_last                  → cover-1.png
edit_last                  → cover-2.png

generate_image (no output) → imgx-a1b2c3d4.png
edit_last                  → imgx-a1b2c3d4-1.png

切换会话 — 使用 edit_history 查看所有会话，然后使用 switch_session 恢复之前的会话。edit_last 工具会使用切换后会话中的当前位置。

输出目录 — edit_last 会继承会话的输出目录。如果调用 generate_image 时指定了 output_dir，则该会话中后续所有 edit_last 调用都会输出到同一目录。output_dir 路径会作为会话元数据记录在 output-history.json 中。这只会影响图像文件的保存位置，历史记录始终保存在 .imgx/（或全局配置目录）中。

API 密钥设置

至少设置一个提供方：

Gemini — 从 Google AI Studio 获取密钥（gemini-2.5-flash-image 提供免费套餐）：

imgx config set api-key YOUR_GEMINI_API_KEY --provider gemini

OpenAI — 从 OpenAI Platform 获取密钥：

imgx config set api-key YOUR_OPENAI_API_KEY --provider openai

密钥存储在 ~/.config/imgx/config.json（Linux/macOS）或 %APPDATA%\imgx\config.json（Windows）中。也可以通过 MCP 配置中的 env 部分传入密钥，或设置环境变量：

export GEMINI_API_KEY="your-api-key"
export OPENAI_API_KEY="your-api-key"

只需包含你想使用的提供方对应的 API 密钥。至少需要一个密钥。

按工具配置 MCP

Claude Code

项目根目录中的 .mcp.json：

{
  "mcpServers": {
    "imgx": {
      "command": "npx",
      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": { "GEMINI_API_KEY": "your-key", "OPENAI_API_KEY": "your-key" }
    }
  }
}

Gemini CLI

~/.gemini/settings.json：

{
  "mcpServers": {
    "imgx": {
      "command": "npx",
      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": { "GEMINI_API_KEY": "your-key", "OPENAI_API_KEY": "your-key" }
    }
  }
}

Claude Desktop

claude_desktop_config.json：

macOS / Linux：

{
  "mcpServers": {
    "imgx": {
      "command": "npx",
      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-key",
        "OPENAI_API_KEY": "your-key",
        "IMGX_PROJECT_ROOT": ""
      }
    }
  }
}

Windows：

{
  "mcpServers": {
    "imgx": {
      "command": "cmd",
      "args": ["/c", "npx", "--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-key",
        "OPENAI_API_KEY": "your-key",
        "IMGX_PROJECT_ROOT": ""
      }
    }
  }
}

IMGX_PROJECT_ROOT — 设置为你的项目路径，即可将图像保存在项目中（例如 "C:\\Users\\you\\my-project"）。留空则使用全局默认目录（~/Pictures/imgx）。

配置文件位置：%APPDATA%\Claude\claude_desktop_config.json（Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）。编辑后，请重启 Claude Desktop。

注意： Claude Desktop 不支持自动检测（MCP 根目录 / 基于 CWD 搜索 .imgxrc）。请在上方配置中使用 IMGX_PROJECT_ROOT（针对每个客户端分别设置），或运行 imgx config set project-root /path/to/project（对所有客户端生效）。

Codex CLI

.codex/config.toml：

[mcp_servers.imgx]
command = "npx"
args = ["--package=imgx-mcp", "-y", "imgx-mcp"]
env = { GEMINI_API_KEY = "your-key", OPENAI_API_KEY = "your-key" }

其他工具

相同的 npx 模式也适用于 Cursor、Windsurf、Continue.dev、Cline、Zed 和其他兼容 MCP 的工具。在 Windows 上，请使用 cmd /c npx，而不是直接使用 npx。

提供方

提供方	模型	功能
Gemini	gemini-2.5-flash-image（Nano Banana — 免费套餐，默认）、gemini-3-pro-image-preview（Nano Banana Pro）、gemini-3.1-flash-image-preview（Nano Banana 2）	生成、编辑、宽高比（最多 14 种比例）、分辨率（最高 4K）、参考图像、人物控制
OpenAI	gpt-image-1、gpt-image-1.5（速度更快，价格低 20%）、gpt-image-1-mini（经济型）	生成、编辑、宽高比、多图输出、输出格式（PNG/JPEG/WebP）、背景透明

架构

imgx 将与模型无关和依赖模型的部分分开：

MCP server (tool definitions, stdio transport)    CLI (argument parsing, output formatting)
 ↓                                                 ↓
Core (Capability enum, ImageProvider interface, provider registry, file I/O, history)
 ↓
Provider (model-specific API calls, capability declarations)

MCP 服务和 CLI 是进入同一核心的两个入口。两者都会调用相同的提供方函数。

每个提供方都会声明其支持的功能。添加新提供方只需实现 ImageProvider 接口并注册，无需更改 MCP 或 CLI 层。

能力系统

能力	描述
TEXT_TO_IMAGE	根据文本提示词生成图像
IMAGE_EDITING	根据文本说明编辑图像
ASPECT_RATIO	控制输出宽高比
RESOLUTION_CONTROL	控制输出分辨率
MULTIPLE_OUTPUTS	每次请求生成多张图像
REFERENCE_IMAGES	使用参考图像提供指引
PERSON_CONTROL	控制输出中的人物生成
OUTPUT_FORMAT	选择输出格式（PNG、JPEG、WebP）

CLI

imgx-mcp 也可作为独立的命令行工具使用。

安装

npm install -g imgx-mcp

需要 Node.js 18+。

用法

# Generate
imgx generate -p "A coffee cup on a wooden table, morning light" -o output.png

# Edit
imgx edit -i photo.png -p "Change the background to sunset" -o edited.png

# Iterative editing
imgx edit -i photo.png -p "Make the background darker"
imgx edit --last -p "Add warm lighting"
imgx edit --last -p "Crop to 16:9" -o final.png

# Undo / redo
imgx undo               # Revert to previous image in session
imgx redo               # Re-apply an undone edit

# History
imgx history            # Show all sessions and entries
imgx history switch <session-id>  # Switch to a different session
imgx history clear      # Clear project history (interactive)
imgx history clear --yes          # Clear without confirmation
imgx history clear --keep-files   # Clear history but keep image files
imgx history clear --all          # Clear ALL history across all projects

# Provider management
imgx providers          # List providers and capabilities
imgx capabilities       # Detailed capabilities of current provider

CLI 选项

标志	简写	描述
--prompt	-p	图像描述或编辑说明（必填）
--output	-o	输出文件路径（省略时自动生成）
--input	-i	要编辑的输入图像（仅限 edit 命令）
--last	-l	使用上一次的输出作为输入（仅限 edit 命令）
--aspect-ratio	-a	1:1、16:9、9:16、4:3、3:4、2:3、3:2 + Gemini 3.x：1:4、1:8、4:1、4:5、5:4、8:1、21:9
--resolution	-r	1K、2K、4K
--count	-n	要生成的图像数量
--format	-f	输出格式：png、jpeg、webp（仅限 OpenAI）
--background	-b	背景：transparent、opaque、auto（仅限 OpenAI）
--quality	-q	质量：low、medium、high、auto（仅限 OpenAI）
--model	-m	模型名称
--provider		提供商名称（默认：gemini）
--output-dir	-d	输出目录

配置

imgx config set api-key <key> --provider gemini   # Save Gemini API key
imgx config set api-key <key> --provider openai   # Save OpenAI API key
imgx config set model <name>      # Set default model
imgx config set output-dir <dir>  # Set default output directory
imgx config set aspect-ratio 16:9 # Set default aspect ratio
imgx config set resolution 2K     # Set default resolution
imgx config list                  # Show all settings
imgx config get api-key           # Show a specific setting (API key is masked)
imgx config path                  # Show config file location

项目配置（.imgxrc）

使用 imgx init 生成模板：

imgx init
# → creates .imgxrc in current directory

或手动创建：

{
  "defaults": {
    "model": "gemini-2.5-flash-image",
    "outputDir": "./assets/images",
    "aspectRatio": "16:9"
  }
}

项目配置通过 Git 共享。请勿将 API 密钥放入 .imgxrc。

项目根目录配置（3 个层级）

方式	作用范围	设置方法
客户端配置中的 IMGX_PROJECT_ROOT 环境变量	每个客户端（优先级最高）	添加到 claude_desktop_config.json、.mcp.json 等文件的 env 中。
自动检测（MCP 根目录 / .imgxrc 搜索）	自动	可用于 CLI Agent（Claude Code、Gemini CLI）。Claude Desktop 不支持
imgx config set project-root	这台机器上的所有客户端	存储在用户配置中（~/.config/imgx/config.json 或 %APPDATA%\imgx\config.json）

检测优先级：环境变量 → MCP 根目录 → 向上搜索 .imgxrc → 用户配置 projectRoot。

历史记录保存到 <project-root>/.imgx/output-history.json（项目范围内，不与其他项目共享）。默认图像输出保存到 <project-root>/.imgx/<session-id>/。output 和 output_dir 中的相对路径会根据项目根目录解析，而不是根据 MCP 服务的工作目录解析。

设置解析顺序

1. CLI 标志（--model、--output-dir 等）
2. 环境变量（IMGX_MODEL、IMGX_OUTPUT_DIR 等）
3. 项目配置（.imgxrc — 从当前目录开始向上搜索）
4. 用户配置（~/.config/imgx/config.json 或 %APPDATA%\imgx\config.json）
5. 提供商默认值

输出格式

所有 CLI 命令均输出 JSON：

{"success": true, "filePaths": ["./output.png"]}

Claude Code 插件

该插件可一步完成 MCP 服务和技能的安装。如果你不想手动配置 .mcp.json 和技能文件：

/plugin marketplace add somacoffeekyoto/imgx-mcp
/plugin install imgx-mcp@somacoffeekyoto-imgx-mcp

更新：/plugin → 已安装 → imgx-mcp → 更新。如果更新后没有变化，请先卸载再重新安装。

卸载：先运行 /plugin uninstall imgx-mcp@somacoffeekyoto-imgx-mcp，然后运行 /plugin marketplace remove somacoffeekyoto-imgx-mcp。

开发

git clone https://github.com/somacoffeekyoto/imgx-mcp.git
cd imgx-mcp
npm install
npm run bundle    # TypeScript compile + esbuild bundle

构建会生成两个打包文件：

• dist/mcp.bundle.js — MCP 服务入口点
• dist/cli.bundle.js — CLI 入口点

卸载

MCP 服务

从工具的 MCP 配置文件中移除 imgx 条目。

技能

从 .claude/skills/ 或 ~/.claude/skills/ 中删除 image-generation/ 目录。

CLI

npm uninstall -g imgx-mcp

npm uninstall 会移除软件包，但不会删除配置或生成的文件。如有需要，请手动删除：

全局配置：

# Linux / macOS
rm -rf ~/.config/imgx/

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:APPDATA\imgx"

项目历史记录和图片： 每个项目都可能包含一个 .imgx/ 目录，其中保存编辑历史记录和生成的图片。请根据需要从各个项目中将其删除。

rm -rf <project-root>/.imgx/

许可证

MIT — SOMA COFFEE KYOTO

链接

• 官方网站
• GitHub
• npm
• Cursor Directory
• MCP 注册表
• SOMA COFFEE KYOTO
• X (@somacoffeekyoto)