米醋画图 MCP

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

默认使用 gpt-image-2 / gpt-image-2-pro。可选配置 MICU_GROK_API_KEY 后，也能走米醋 Grok 图像通道。

注意：米醋后台的 Image2 分组和 Grok 分组通常是两把不同的 key：

• MICU_API_KEY: Image2 分组 token，必须能看到 gpt-image-2 / gpt-image-2-pro

• MICU_GROK_API_KEY: Grok 图像分组 token，必须能看到 grok-imagine-image-*

如果把 Grok 分组 token 填进 MICU_API_KEY，运行时会出现类似 分组 grok 下模型 gpt-image-2 无可用渠道 的错误。

当前实测 Grok 图像模型包括：

• grok-imagine-image-lite

• grok-imagine-image

• grok-imagine-image-pro

• grok-imagine-image-edit

功能

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

Related MCP server: imagine-mcp

使用教程

面向 Cursor / Claude Code / Codex 用户的完整 MCP 使用指南见 docs/MCP使用教程.md， 涵盖工具选型、尺寸规则、环境变量与故障排查（含 Clash/Surge fake-ip 落盘问题）。

Grok 与 GPT Image2 功能差异

2026-07 线路兼容更新：支持将限流包装为 HTTP 400 + Too Many Requests 的新线路行为，并按 429 语义自动重试；同时兼容 response_format=url 返回 data:image/...;base64,...。实测 https://www.micuapi.ai 经 Cloudflare LAX + Caddy 正常，1K 可用；4K/pro 队列仍可能受上游限流，因此仅保留纯文生图 4K，参考图 4K 暂不放开。

Windows 中文提示词：MCP 会以原生 UTF-8 JSON 发送中文。自行编写 PowerShell 测试脚本时，不要把含中文的 here-string 直接通过管道喂给 python -；Windows PowerShell 的 $OutputEncoding 可能是 ASCII，导致中文在进入 MCP 前已变成 ?。请将脚本保存为 UTF-8 文件后执行，或先设置 $OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()。

一键安装

方式一：用 Git 下载源码（推荐）。

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

以后更新同一个目录：

cd micu-image-mcp
git pull --ff-only
python install.py

方式二：用 npm 临时下载源码（适合没有 git 命令的环境）。这个项目不是 npm 包，不要用 npm install micu-image-mcp；下面的命令只是通过 tiged 从 GitHub 拉取源码，仍需要当前网络能访问 GitHub。

npm exec --yes tiged -- github:Subaru486desuwa/micu-image-mcp#main micu-image-mcp
cd micu-image-mcp
python install.py

脚本会：

1. 检查 Python >= 3.10

2. 安装依赖

3. 交互配置米醋 Image2 分组 API key、输出目录

4. 可选配置米醋 Grok 生图分组 token

5. 写入 ~/.claude.json 和 ~/.codex/config.toml

6. 启动 server 做一次 initialize 握手

安装脚本会用 /v1/models 做轻量校验，尽量在安装阶段发现 key 分组粘错的问题。

非交互安装：

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

--yes 模式下如果 MICU_API_KEY 看不到 gpt-image-2，或 MICU_GROK_API_KEY 看不到 grok-imagine-image-*，安装会直接失败，避免写入错误配置。

常用选项：

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

卸载/重置（仅删 MCP 配置节，不动 pip 包）：

python install.py --reset
# 想顺手卸 pip 包再加:
python -m pip uninstall -y micu-image-mcp

--reset 会备份原配置后，从 ~/.claude.json 移除 mcpServers.micu-image、从 ~/.codex/config.toml 移除 [mcp_servers.micu-image] 整节，其他 MCP server 节点保持不动。

安装完成后会自动跑一次 initialize 握手 + tools/list，预期能看到 5 个 tool：image_generate / image_edit / image_batch_edit / image_multi_reference / server_info。安装日志里看到这 5 个名字才算装好。然后重启 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 可选：

建议仍优先用常见比例和不太小的边长，例如 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 队列

推荐 size：

Grok 路径：

• 不强制 8 倍数

• 当前按 1K / 2K 路由

• 4K 请求会映射到 resolution=2k

尺寸能力矩阵 / Size capability

实测确认的真实能力（image2 路径）。1K 档可靠输出 ~1.57MP；纯文生图 2K/4K 真分辨率可用（pro + 重试）；带参考图 2K 为 best-effort 真 2K。

说明：

• /v1/images/edits 是米醋唯一真正消费输入图的端点。1K 档稳定输出 ~1.57MP；2K 档自动切 pro 后 best-effort 真 2K（压测约 2/3 成功真返回 2048×2048，524 时 fallback chat stream → ~1.57MP，较慢 2-4 分钟/单次）。

• 旧的 generations + reference_image（单图 2K）和 generations + image_urls（多图）路径要么 524 断流、要么参考图被静默忽略，已废弃。

• 带参考图想要真 4K 用两步法：先出一张 ~1.57MP/2K 的综合/编辑图 → 再用 image_generate 描述同场景升 4K（image_generate 4K 真分辨率可用，自动切 pro + MCP 重试吸收瞬时 524）。

环境变量

兼容旧 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"

性能 / 压力测试

tests/ 下两个独立脚本，直接 in-process import server.py 调 image_generate，不走 stdio MCP（避免子进程开销污染样本）。需要至少一个有效 key 才能跑真实请求；不带 key 用 --dry-run 也能验证脚本/导入/校验链路。

报告默认落到 tests/reports/<title>_<ts>.{json,md}，已被 .gitignore 排除。生成的图扔到 /tmp/micu-bench/<label>/，不会污染你的 ~/Pictures/micu-out。

性能基线 tests/perf_bench.py

串行跑 image2 / Grok 在不同 size 下的 image_generate，记录单次延迟、actual_size 偏差、保存后字节数。

# smoke (默认): image2 + grok 各 2 张, 共 4 张 → ~3-5 分钟
python tests/perf_bench.py

# 完整 sweep, 每组重复 3 次
python tests/perf_bench.py --full --repeat 3

# 只跑某一通道
python tests/perf_bench.py --channels image2
python tests/perf_bench.py --channels grok

# 干跑 (不打 API, 只验证脚本链路)
python tests/perf_bench.py --dry-run

报告 markdown 表头：group | n | ok | fail | rate | p50_ms | p95_ms | mean_ms | actual_match。actual_match 是 PNG header 读出的实际像素严格等于请求 size 的比例 — 对 image2 1K 福利档预期会偏低（被代理压到 ~1.57MP），2K/4K 严格 1:1，Grok 由 MICU_GROK_SIZE_MODE 决定。

并发压力 tests/stress_concurrent.py

验证：

1. 1K 单进程多并发 → 进程内不卡，吞吐近似线性

2. ≥2K 多进程并发 → 进程内 asyncio.Semaphore(1) + 跨进程 flock 双层锁串行

3. CF 524 / 上游 5xx → 重试/fail-fast 策略

4. Grok 路径不走 ≥2K 锁，可线性并发

# in-process 并发 (默认 smoke, image2 1K x 3)
python tests/stress_concurrent.py

# 验证 ≥2K 锁串行
python tests/stress_concurrent.py --size 2048x2048 --concurrency 4

# 跨进程模式 (spawn N 个子进程, 模拟多 Claude Code 窗口)
python tests/stress_concurrent.py --mode multiprocess --concurrency 3 --size 2048x2048

# Grok 并发
python tests/stress_concurrent.py --model grok-imagine-image-lite --concurrency 5

报告关键派生指标：

提醒：image2 真实并发会按米醋后台 pro 队列限流计费，跑 --concurrency ≥ 3 之前先确认账户额度。dry-run / 401 路径不计费。