imgx MCP

imgx mcp

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

人工智能图像生成和编辑MCP服务器。适用于Claude Code、Gemini CLI、Cursor、Windsurf和任何兼容MCP的工具。

从文本生成图像，用文本指令编辑现有图像，迭代结果——所有这些都来自您的AI编码环境。

是什么让imgx mcp与众不同

• 没有及时的工程 --您的AI代理保持对话上下文并自动构建优化的提示。说出你需要什么；代理处理提示结构、模型选择和特定于平台的大小调整
• 内置24种编辑技术 --氛围、构图、风格转换、元素操作和趋势风格——捆绑在你的经纪人按需应用的技能中
• 具有撤消/重做功能的会话管理 --迭代编辑、后退到任何点、分支或在并行会话之间切换——图像的版本控制

快速开始

添加到工具的MCP配置中(.mcp.json, settings.json等等）：

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

就是这样。你的AI代理现在可以生成和编辑图像了。

视窗：替换 "command": "npx" 和 "command": "cmd" 并预置 "/c" 到args数组。

技能（克劳德代码）

对于Claude Code用户，imgx mcp包括一个 image-generation 技能——一个指导性的提示，教克劳德如何有效地使用MCP工具。安装技能后，键入 /image-generation 启动一个有指导的工作流程。

安装技能

将技能目录从npm包或GitHub存储库复制到您的项目中：

# 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

或者手动放置技能文件：

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

技能档案包含在 在...之下 skills/ 在 .

个人技能 （所有项目）：地点 ~/.claude/skills/image-generation/ 而不是 .claude/skills/.

克劳德桌面版

Claude Desktop通过ZIP上传支持技能：

1. 下载 image-generation-skill.zip 从存储库（或在 在...之下 dist/)
2. 在克劳德桌面中： 设置>个人资料>自定义>技能>添加技能
3. 上传ZIP

在新版本发布后，通过重新下载和上传ZIP来更新技能。

技能带来什么

MCP服务器为AI提供 *能力* 以生成和编辑图像。该技能增加了 *知识* 如何很好地使用这些工具——所以你不需要学习提示语法、模型规范或特定于服务的参数。

• 自动提示施工 --说“我需要一张封面图片。”人工智能使用主题上下文风格框架构建了一个结构化的提示：显示什么，放在哪里，应该是什么样子
• 24种编辑技巧 --气氛调整、构图变化、元素操作、风格转换。“让它更暖和”或“增加景深”——人工智能为模型选择正确的指令
• 智能选型 --从免费模式开始。仅当您的需求超过免费层功能时，才建议付费升级，并解释了哪些变化
• 平台感知尺寸 --“推特OGP”或“应用商店截图”——人工智能会选择正确的纵横比和分辨率。涵盖社交媒体、OGP、应用商店、印刷和博客平台
• 流行风格模板 --吉卜力、盒子里的动作人偶、3D粘土、像素艺术、赤壁等等。命名样式，AI应用正确的提示结构
• 多图像一致性 --设计代币和角色DNA模板保持幻灯片、社交媒体系列和品牌资产之间的视觉连贯性

图像生成模型已经具备这些功能。技能是使他们在没有专业知识的情况下能够接触到的东西。

MCP服务器vs技能

推荐：设置MCP服务器（快速入门）+如果您使用Claude Code，请安装该技能。

MCP工具

这 .imgx/ 该目录同时保存编辑历史记录和默认图像输出。其位置取决于项目根检测：

解析到同一项目根目录的所有客户端共享相同的历史记录。每个会话都有自己的子目录。响应中返回文件路径。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密钥设置

设置至少一个提供程序：

双子座 --从以下位置获取密钥 谷歌AI工作室 （免费套餐适用于 gemini-2.5-flash-image):

imgx config set api-key YOUR_GEMINI_API_KEY --provider gemini

开放人工智能 --从以下位置获取密钥 OpenAI平台:

imgx config set api-key YOUR_OPENAI_API_KEY --provider openai

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

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

仅包括要使用的提供程序的API密钥。至少需要一个。

按工具配置MCP

克劳德代码

.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/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_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": ""
      }
    }
  }
}

窗户：

{
  "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 直接。

提供商

建筑

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层。

能力系统

命令行界面

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   # 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选项

配置

imgx config set api-key  --provider gemini   # Save Gemini API key
imgx config set api-key  --provider openai   # Save OpenAI API key
imgx config set model       # Set default model
imgx config set output-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层）

检测优先级：env-var→ MCP根→ .imgxrc 向上搜索→ 用户配置 projectRoot.

历史记录保存到 /.imgx/output-history.json （项目范围，不与其他项目共享）。默认图像输出转到 /.imgx//.中的相对路径 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代码插件

该插件将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服务器

移除 imgx 从工具的MCP配置文件中输入。

技能

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

命令行界面

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 
/.imgx/

许可证

麻省理工学院-- 京都苏玛咖啡

链接

• 官方网站
• 光标目录
• MCP注册表
• 京都苏玛咖啡
• X（@somacoffee-kyoto）