MCP 服务器

Micu Image MCP

Wraps the Micu image API as an MCP server for generating, editing, batch processing, and multi-reference image fusion, supporting GPT-image-2 and Grok models.

README

米醋画图 MCP

把米醋的图像接口包装成 MCP server，让 Claude Code / Codex / Cursor 等 MCP 客户端直接生图、改图、批处理、多图参考。

默认使用 gpt-image-2 / gpt-image-2-pro。可选配置 MICU_GROK_API_KEY 后，也能走米醋 Grok 图像通道，当前实测模型包括：

grok-imagine-image-lite
grok-imagine-image
grok-imagine-image-pro
grok-imagine-image-edit

功能

Tool	说明
`image_generate`	文生图。米醋 image2 支持 1K / 2K / 4K；Grok 支持 1K / 2K 路由
`image_edit`	单图参考/编辑。image2 走 edits 或 `reference_image`；Grok 走 `reference_image`
`image_batch_edit`	多张图逐张同指令处理
`image_multi_reference`	2-10 张参考图融合成 1 张新图；Grok 走 `image_urls`
`server_info`	查看 base URL、模型、size 规则、重试策略、安全约束

第一次使用前，让 LLM 调一次 server_info，可以看到当前运行时配置和可用能力。

Grok 与 GPT Image2 功能差异

能力	`gpt-image-2` / `gpt-image-2-pro`	米醋 Grok 图像模型
默认用途	主通道，覆盖文生图、图生图、批量编辑、多图参考	可选通道，适合快速文生图、单图参考、多图参考
可选模型	`gpt-image-2`, `gpt-image-2-pro`	`grok-imagine-image-lite`, `grok-imagine-image`, `grok-imagine-image-pro`, `grok-imagine-image-edit`
`image_generate` 文生图	支持 1K / 2K / 4K；2K/4K 自动切 pro，强制 `n=1`	支持 1K / 2K 路由；`n` 会传给后端，实际返回张数以响应为准
`image_edit` 单图参考/编辑	1K 走 `/v1/images/edits`；2K 走 `reference_image`；4K 参考图入口拒绝	走 `/v1/images/generations` + `reference_image`；4K 会映射到 `resolution=2k`
局部 mask	仅 1K edits multipart 支持 alpha mask；2K 不支持	当前不支持 mask，传入会忽略并写入 `notes`
`image_multi_reference` 多图参考	2-10 张参考图；1K 稳定，2K 可能 fallback，4K 入口拒绝	2-10 张参考图走 `image_urls`；实测可用，按 `resolution` + `aspect_ratio` 映射
`image_batch_edit` 批量逐张编辑	支持 1K；non-pro 5 并发，pro 串行	当前不支持 Grok 批量逐张编辑
size 校验	`WxH`，边长 256-4096，W/H 必须是 8 的倍数	只校验 `WxH` 正整数，不强制 8 倍数和 4096 边长
实际输出尺寸	≥4MP 通常严格 1:1；≤2.25MP 会被代理处理到约 1.57MP	不保证等于请求 `WxH`，以 `saved.actual_size` 为准
重试/限流	2K/4K 使用跨进程锁，避免多个 MCP 同时打 pro 队列	不走高分辨率锁；可恢复错误仍自动重试并记录到 `notes`
配置变量	`MICU_API_KEY`, `MICU_MODEL`, `MICU_BASEURL`	`MICU_GROK_API_KEY`, `XAI_MODEL`；默认复用 `MICU_BASEURL`

一键安装

git clone https://github.com/Subaru486desuwa/micu-image-mcp.git
cd micu-image-mcp
python install.py

脚本会：

检查 Python >= 3.10
安装依赖
交互配置米醋 API key、输出目录
可选配置米醋 Grok 生图 token
写入 ~/.claude.json 和 ~/.codex/config.toml
启动 server 做一次 initialize 握手

非交互安装：

MICU_API_KEY=sk-... \
MICU_GROK_API_KEY=sk-... \
MICU_SAVE_DIR=~/Pictures/micu-out \
python install.py --yes

常用选项：

python install.py --no-codex
python install.py --no-claude
python install.py --mirror tsinghua
python install.py --baseurl https://www.micuapi.ai

安装完成后重启 Claude Code / Codex，让 LLM 调 server_info 验证。

Grok 路径

Grok 走米醋中转，base URL 默认仍是：

https://www.micuapi.ai

只需要额外配置：

MICU_GROK_API_KEY=sk-...
XAI_MODEL=grok-imagine-image-lite
MICU_GROK_SIZE_MODE=contain

Grok 的 size 不套用 image2 的 8 倍数和 4096 边长约束。本地只检查 WxH 格式，然后映射为：

resolution: 1k 或 2k
aspect_ratio: 最接近的比例，如 1:1、16:9、9:16

注意：Grok 后端返回像素不保证严格等于请求的 WxH。MCP 默认会在保存前用 Pillow 把 Grok 输出归一化到请求尺寸，MICU_GROK_SIZE_MODE 可选：

值	行为
`contain`	默认。等比缩放，补边到请求尺寸，不裁主体
`cover`	等比缩放并居中裁切，铺满请求尺寸
`stretch`	直接拉伸到请求尺寸，可能变形
`backend`	不做本地后处理，保留 Grok 后端原始像素

建议仍优先用常见比例和不太小的边长，例如 1024x1024、1536x1024、1024x1536、1501x1001。过小或很奇异的比例可能被米醋 Grok 后端返回 500，MCP 会自动重试并在 notes 里记录。

Size 规则

image2 路径：

W/H 必须是 8 的倍数
W/H 必须在 256 到 4096 范围内
1K 福利档可能被代理处理到约 1.57MP
2K/4K 自动切 gpt-image-2-pro
2K/4K 强制 n=1 并加跨进程锁，避免多个 MCP 同时打爆 pro 队列

档位	推荐值
1K	`1024x1024`, `1280x720`, `720x1280`, `1024x1536`, `1536x1024`
2K	`2048x2048`, `2048x1152`, `1152x2048`
4K	`3840x2160`, `2160x3840`

环境变量

变量	默认值	说明
`MICU_API_KEY`	空	米醋 image2 token
`MICU_BASEURL`	`https://www.micuapi.ai`	米醋 base URL
`MICU_MODEL`	`gpt-image-2`	image2 默认模型
`MICU_GROK_API_KEY`	空	米醋 Grok 图像 token
`XAI_MODEL`	`grok-imagine-image-lite`	Grok 默认模型
`MICU_GROK_SIZE_MODE`	`contain`	Grok 保存前尺寸归一化策略：`contain` / `cover` / `stretch` / `backend`
`MICU_SAVE_DIR`	`~/Pictures/micu-out`	默认输出目录
`MICU_SAVE_DIR_ROOT`	同输出目录	输出安全根目录
`MICU_USE_SHELL_PROXY`	`0`	设为 `1` 才读取 shell 代理

兼容旧 Grok 变量 XAI_API_KEY / GROK_API_KEY，但推荐新配置统一使用 MICU_GROK_API_KEY。

手动配置

Claude Code:

{
  "mcpServers": {
    "micu-image": {
      "command": "/path/to/python",
      "args": ["/absolute/path/to/micu-image-mcp/server.py"],
      "env": {
        "MICU_API_KEY": "sk-...",
        "MICU_GROK_API_KEY": "sk-...",
        "MICU_SAVE_DIR": "/Users/you/Pictures/micu-out",
        "MICU_SAVE_DIR_ROOT": "/Users/you/Pictures/micu-out",
        "XAI_MODEL": "grok-imagine-image-lite"
      }
    }
  }
}

Codex:

[mcp_servers.micu-image]
command = "/path/to/python"
args = ["/absolute/path/to/micu-image-mcp/server.py"]

[mcp_servers.micu-image.env]
MICU_API_KEY = "sk-..."
MICU_GROK_API_KEY = "sk-..."
MICU_SAVE_DIR = "/Users/you/Pictures/micu-out"
MICU_SAVE_DIR_ROOT = "/Users/you/Pictures/micu-out"
XAI_MODEL = "grok-imagine-image-lite"