Micu Image MCP

Envuelve la interfaz de imágenes de Micu como un servidor MCP, permitiendo que clientes MCP como Claude Code / Codex / Cursor generen, editen, procesen por lotes y usen múltiples imágenes de referencia directamente.

Actualmente solo admite gpt-image-2 / gpt-image-2-openai; MICU_API_KEY debe poder ver estos dos modelos. El canal de generación de imágenes de Grok está temporalmente cerrado y se habilitará cuando el servidor lo soporte; incluso si se configuran las antiguas variables de entorno de Grok, el instalador no las escribirá, y las llamadas a herramientas rechazarán los modelos Grok antes de enviar la solicitud.

Funciones

Antes del primer uso, haz que el LLM llame a server_info una vez para ver la configuración de ejecución actual y las capacidades disponibles.

Related MCP server: gpt-image-2-mcp

Guía de uso

La guía completa de uso de MCP para usuarios de Cursor / Claude Code / Codex está en docs/MCP使用教程.md, que cubre la selección de herramientas, reglas de tamaño, variables de entorno y solución de problemas (incluido el problema de escritura en disco de fake-ip de Clash/Surge).

Alcance del modelo actual

Todas las herramientas y scripts de prueba de carga solo aceptan gpt-image-2 y gpt-image-2-openai. 2K/4K cambia automáticamente a la línea de alta calidad gpt-image-2-openai; la implementación relacionada con Grok se mantiene temporalmente como código inactivo y se puede reabrir cuando el servidor vuelva a soportarla.

Actualización de línea actual 2026-08-14: La generación y edición de gpt-image-2 / gpt-image-2-openai ahora usan unificadamente la API de Images actual; se ha eliminado el bloqueo duro de la línea antigua para imágenes de referencia 4K. 2K / 4K cambia automáticamente a gpt-image-2-openai y entra en la cola de alta calidad en serie, sin necesidad de pasar por el paso intermedio de hacer 1K/2K y luego generar texto a imagen para subir a 4K. También se mantiene la compatibilidad con HTTP 400 + Too Many Requests y las respuestas data:image/...;base64,....

Indicaciones en chino en Windows: MCP envía chino como JSON UTF-8 nativo. Al escribir scripts de prueba de PowerShell, no pases here-strings con chino directamente por pipe a python -; el $OutputEncoding de Windows PowerShell puede ser ASCII, lo que convierte el chino en ? antes de que llegue a MCP. Guarda el script como archivo UTF-8 antes de ejecutarlo, o establece primero $OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new().

Instalación con un clic

Opción 1: Descargar el código fuente con Git (recomendado).

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

Para actualizar el mismo directorio en el futuro:

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

Opción 2: Descargar temporalmente el código fuente con npm (adecuado para entornos sin el comando git). Este proyecto no es un paquete npm, no uses npm install micu-image-mcp; el siguiente comando solo usa tiged para extraer el código fuente de GitHub, y aún se necesita acceso a GitHub desde la red actual.

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

El script hará:

1. Verificar Python >= 3.10

2. Instalar dependencias

3. Configurar interactivamente la API key del grupo Image2 de Micu y el directorio de salida

4. Escribir ~/.claude.json y ~/.codex/config.toml

5. Iniciar el servidor y hacer un handshake de initialize

El script de instalación usará /v1/models para una verificación ligera, detectando en la fase de instalación si la key se pegó en el grupo incorrecto.

Instalación no interactiva:

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

En modo --yes, si MICU_API_KEY no puede ver gpt-image-2 / gpt-image-2-openai, la instalación fallará directamente, evitando escribir una configuración incorrecta.

En macOS, si no quieres escribir la API key a largo plazo en texto plano en la configuración de MCP, puedes guardarla en el llavero de inicio de sesión y hacer que el comando STDIO MCP de Codex apunte a scripts/run-mcp-macos-keychain.sh:

security add-generic-password \
  -U -a "$USER" -s ai.micuapi.mcp \
  -l "Micu Image MCP API Key" \
  -T /usr/bin/security -w

El comando leerá la key interactivamente y no la dejará en el historial del shell. La configuración de MCP solo necesita conservar variables no sensibles:

[mcp_servers.micu-image]
command = "/absolute/path/micu-image-mcp/scripts/run-mcp-macos-keychain.sh"
args = []

[mcp_servers.micu-image.env]
MICU_BASEURL = "https://www.micuapi.ai"
MICU_MODEL = "gpt-image-2"
MICU_KEYCHAIN_SERVICE = "ai.micuapi.mcp"
MICU_KEYCHAIN_ACCOUNT = "your-macos-account"

Codex de escritorio, CLI y la extensión de IDE comparten ~/.codex/config.toml; después de guardar, reinicia el cliente para que el subproceso MCP vuelva a leer la configuración.

Opciones comunes:

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

Desinstalar/restablecer (solo elimina las secciones de configuración de MCP, no toca el paquete pip):

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

--reset hará una copia de seguridad de la configuración original y luego eliminará mcpServers.micu-image de ~/.claude.json y toda la sección [mcp_servers.micu-image] de ~/.codex/config.toml, dejando intactos los demás nodos de servidores MCP.

Después de la instalación, se ejecutará automáticamente un handshake initialize + tools/list; se espera ver 5 herramientas: image_generate / image_edit / image_batch_edit / image_multi_reference / server_info. Solo cuando veas estos 5 nombres en el registro de instalación estará correctamente instalado. Luego reinicia Claude Code / Codex y haz que el LLM llame a server_info para verificar.

Reglas de tamaño

Ruta image2:

• W/H deben ser múltiplos de 16

• El lado más largo no debe superar 3840; la relación de aspecto no debe superar 3:1

• El total de píxeles debe estar entre 655,360 y 8,294,400

• 2K/4K cambia automáticamente a gpt-image-2-openai

• 2K/4K fuerza n=1 y añade un bloqueo entre procesos para evitar que múltiples MCP saturen la cola de alta calidad

Tamaños recomendados:

Matriz de capacidades de tamaño / Size capability

Verificado el 2026-08-14: ambas líneas Image2 actuales pueden generar y editar; la línea de alta calidad devuelve exactamente 1536×1024, 2048×1152, 3840×2160, mientras que algunos tamaños personalizados de la línea estándar son reasignados por el backend. El MCP actual también ha habilitado la referencia de imágenes 4K, sin el rechazo local de la línea antigua.

Notas:

• /v1/images/edits es el endpoint donde Micu realmente consume las imágenes de entrada. Las ediciones de referencia de una sola imagen en 1024², 2048×1152 y 3840×2160 ya han sido verificadas.

• Las rutas antiguas generations + reference_image y generations + image_urls están obsoletas; todas las solicitudes de referencia de imágenes Image2 no volverán a las rutas antiguas ni a /v1/chat/completions.

• Las imágenes de referencia 4K se pueden solicitar directamente; 2K/4K cambia automáticamente a gpt-image-2-openai y usa un bloqueo de doble capa (intraproceso + entre procesos) para acceder en serie a la cola de alta calidad.

Variables de entorno

Configuración manual

Claude Code:

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

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_SAVE_DIR = "/Users/you/Pictures/micu-out"
MICU_SAVE_DIR_ROOT = "/Users/you/Pictures/micu-out"

Pruebas de rendimiento / estrés

Dos scripts independientes en tests/, que importan server.py in-process directamente para llamar a image_generate, sin pasar por stdio MCP (para evitar que la sobrecarga de subprocesos contamine las muestras). Se necesita al menos una key válida para ejecutar solicitudes reales; sin key, con --dry-run también se puede verificar el script/importación/cadena de validación.

Los informes se guardan por defecto en tests/reports/<title>_<ts>.{json,md}, excluidos por .gitignore. Las imágenes generadas se envían a /tmp/micu-bench/<label>/, sin contaminar tu ~/Pictures/micu-out.

Línea base de rendimiento tests/perf_bench.py

Ejecuta en serie image_generate de gpt-image-2 / gpt-image-2-openai en diferentes size, registrando latencia por solicitud, desviación de actual_size y bytes después de guardar.

# smoke（默认）：两个 Image2 模型各 1 张
python tests/perf_bench.py

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

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

Encabezados de tabla del informe markdown: group | n | ok | fail | rate | p50_ms | p95_ms | mean_ms | actual_match. actual_match es la proporción de píxeles reales leídos del encabezado de la imagen que son estrictamente iguales al tamaño solicitado; no asumas que el backend respeta los tamaños personalizados.

Estrés de concurrencia tests/stress_concurrent.py

Verifica:

1. 1K múltiples concurrencias en un solo proceso → sin bloqueo intraproceso, rendimiento aproximadamente lineal

2. ≥2K concurrencia entre procesos → asyncio.Semaphore(1) intraproceso + flock entre procesos, bloqueo de doble capa en serie

3. CF 524 / 5xx del proveedor → estrategia de reintento/fail-fast

4. --model solo acepta gpt-image-2 / gpt-image-2-openai

# 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

Métricas derivadas clave del informe:

Recordatorio: La concurrencia real de Image2 se factura según la limitación de la línea del backend de Micu; antes de ejecutar --concurrency ≥ 3, confirma el saldo de tu cuenta. Las rutas dry-run / 401 no se facturan.