# ⚡ kieboost-mcp

Servidor MCP (Model Context Protocol) que conecta Claude (o cualquier cliente MCP) con la API de [kie.ai](https://kie.ai) — acceso unificado a más de 30 modelos de IA para generación de imagen, video y audio, todo bajo un mismo servidor y un mismo API key.

> El paquete npm y el binario local se siguen llamando `kie-ai-mcp` — `kieboost-mcp` es el nombre de este repositorio.

Este repositorio es un **fork ampliamente reescrito** del proyecto original [`neokahu/kie-ai-mcp`](https://github.com/neokahu/kie-ai-mcp) (v1.0.0, MIT). La estructura base del servidor (protocolo MCP, patrón de tools) viene de ahí; **todo el desarrollo posterior — corrección de bugs reales, incorporación de los modelos flagship más usados, reescritura de la lógica de enrutamiento de Veo3/Aleph, y esta documentación — es autoría y desarrollo de RF Consultoría Integral.**

---

## Alcance: qué resuelve este servidor

kie.ai agrega decenas de modelos de generación de medios (imagen, video, voz, música) detrás de una sola API. Este servidor MCP expone esos modelos como *tools* que Claude puede invocar directamente en una conversación — sin que el usuario tenga que salir a una consola, copiar/pegar JSON, o manejar polling manual de tareas asíncronas.

En la práctica, permite pedirle a Claude cosas como *"genera una imagen fotorrealista de un consultorio médico en 4K"* o *"anima esta imagen de referencia a video con Veo3"*, y Claude ejecuta la llamada correcta, espera el resultado, y entrega la URL final — todo dentro del mismo hilo de trabajo.

### Capacidades por categoría

**Imagen** — generación texto→imagen, edición con imágenes de referencia, upscaling, remoción de fondo, reencuadre de aspect ratio. Modelos: Nano Banana 2 / Pro (Gemini 3.1 Flash), Seedream 5.0 Pro, GPT Image 2, Google Imagen 4 / 4 Ultra, Ideogram V3 (generate/edit/remix/reframe), Flux 2, Wan 2.7 Image / Pro, Topaz (upscaling), Recraft (remoción de fondo, upscaling nítido).

**Video** — texto→video, imagen→video, avatares con voz, lip-sync, video-a-video. Modelos: Kling 2.6 / 3.0 / V3 Turbo, Kling Avatar, PixVerse V6, Wan 2.7 (texto/imagen/video, animate), Seedance v1 y 2.0 (ByteDance), Hailuo, Sora 2 / Pro, **Google Veo3.1** (vía su API dedicada `/veo/*`, con soporte para extender videos y obtener renders en 1080p/4K), **Runway Aleph** (vía su API dedicada `/aleph/*`, video-a-video), InfiniTalk (lip-sync).

**Audio** — Suno (generación musical con IA), ElevenLabs (texto a voz y efectos de sonido, ambos vía kie.ai).

**Utilidades** — consulta de estado de tarea (`get_task_status`, con detección automática de la API correcta según el tipo de modelo), conversión de URLs de kie.ai a links de descarga directa, consulta de saldo de créditos.

Todas las herramientas de generación son **asíncronas**: la llamada inicial devuelve un `taskId`, y el resultado se obtiene sondeando `get_task_status` hasta que el estado sea `success` (o usando las tools dedicadas de Veo3/Aleph, que tienen su propio ciclo de vida).

## Qué se corrigió y mejoró respecto al original

El repositorio original tenía varios problemas reales, verificados contra la documentación oficial de kie.ai y corregidos en este fork:

| Problema encontrado | Corrección |
|---|---|
| Veo3 y Runway Aleph se enrutaban por el flujo genérico `createTask` del Market, que no es la API correcta para esos modelos | Se reescribió el enrutamiento para usar sus endpoints dedicados `/veo/*` y `/aleph/*` |
| El identificador de modelo para Kling 3.0 era inválido (`kling-3.0`) | Corregido a `kling-3.0/video` |
| `get_credit_balance` leía `response.data.credit`, pero la API real devuelve `data` como un número plano | Corregido el parseo |
| `list_tasks` era código muerto sin endpoint real correspondiente en kie.ai | Eliminado |
| El README listaba herramientas (`flux_kontext_image`, `qwen_image`, `z_image`, `grok_imagine`, `midjourney_generate`) que nunca estuvieron implementadas | Documentación corregida para reflejar únicamente lo que existe en `src/tools.ts` |
| Faltaban los modelos más usados y de mejor calidad del catálogo actual de kie.ai | Se agregaron Nano Banana 2/Pro, Seedream 5.0 Pro, GPT Image 2, Kling V3 Turbo, PixVerse V6, Wan 2.7 (imagen y video), Seedance 2.0, extensión de Veo3, y utilidades de descarga/renders de alta resolución |

## Configuración

### Requisitos

- Node.js 18+
- Un API key de kie.ai ([kie.ai/api-key](https://kie.ai/api-key))

### Instalación

```bash
git clone https://github.com/Consultoriaintegralrf/kieboost-mcp.git kie-ai-mcp
cd kie-ai-mcp
npm install
npm run build
```

### Variables de entorno

El servidor lee la API key **del entorno**, no de ningún archivo dentro del repositorio. Crea tu propio `.env` local (excluido de git) con:

```
KIE_AI_API_KEY=tu-api-key-aqui
KIE_AI_CALLBACK_URL=   # opcional — webhook para notificación de tareas completadas
```

Este repositorio **no incluye ninguna API key ni configuración de cuenta**. Cada quien usa sus propias credenciales.

### Registrar el servidor en Claude Code

Opción rápida:

```bash
claude mcp add kie-ai -- node --env-file=/ruta/a/kie-ai-mcp/.env /ruta/a/kie-ai-mcp/dist/index.js
```

O agregando manualmente a `.mcp.json` (proyecto) o `~/.claude/settings.json` (global):

```json
{
  "mcpServers": {
    "kie-ai": {
      "command": "node",
      "args": [
        "--env-file=/ruta/a/kie-ai-mcp/.env",
        "/ruta/a/kie-ai-mcp/dist/index.js"
      ]
    }
  }
}
```

Reinicia Claude Code después de agregar el servidor.

### Uso básico

```
1. Llama a una tool de generación (ej. nano_banana_image, veo3_generate_video)
2. Recibe un taskId
3. Sondea con get_task_status hasta que el estado sea "success"
4. Las URLs del resultado expiran a los 14 días — descárgalas o usa get_download_url
```

## Catálogo completo de tools

| Tool | Tipo | Descripción |
|---|---|---|
| `nano_banana_image` | Imagen | Gemini 3.1 Flash (Nano Banana 2) — generación/edición |
| `nano_banana_pro_image` | Imagen | Nano Banana Pro — generación/edición |
| `nano_banana_edit` | Imagen | Nano Banana Edit (edición de imagen) |
| `seedream_image` | Imagen | Seedream 5.0 Pro texto→imagen/edición (flagship ByteDance) |
| `gpt_image2` | Imagen | GPT Image 2 texto→imagen/edición (flagship OpenAI, hasta 4K) |
| `google_imagen4` | Imagen | Google Imagen 4 |
| `google_imagen4_ultra` | Imagen | Google Imagen 4 Ultra |
| `ideogram_v3_generate` | Imagen | Ideogram V3 texto→imagen |
| `ideogram_v3_edit` | Imagen | Ideogram V3 edición con máscara |
| `ideogram_v3_remix` | Imagen | Ideogram V3 remix de imagen |
| `ideogram_v3_reframe` | Imagen | Ideogram V3 adaptación de aspect ratio |
| `flux2_image` | Imagen | Flux 2 Pro/Flex |
| `openai_4o_image` | Imagen | Generación GPT-4o image (endpoint dedicado) |
| `topaz_upscale_image` | Imagen | Upscaling con Topaz AI |
| `recraft_remove_background` | Imagen | Remoción de fondo |
| `recraft_crisp_upscale` | Imagen | Upscaling nítido con Recraft |
| `wan_image` | Imagen | Wan 2.7 Image |
| `wan_image_pro` | Imagen | Wan 2.7 Image Pro |
| `kling_video` | Video | Kling 2.6/3.0 (id de modelo corregido para 3.0: `kling-3.0/video`) |
| `kling_avatar` | Video | Avatares con Kling |
| `kling_turbo_video` | Video | Kling V3 Turbo texto/imagen→video (tier rápido/pro, muy usado) |
| `pixverse_video` | Video | PixVerse V6 texto/imagen→video (costo-eficiente, muy adoptado) |
| `wan27_video` | Video | Wan 2.7 texto/imagen→video/continuación (generación actual de Wan) |
| `bytedance_seedance_video` | Video | Seedance v1 lite/pro (legado) |
| `bytedance_seedance2_video` | Video | Seedance 2.0 (actual: video/audio de referencia, audio nativo, 4K) |
| `hailuo_video` | Video | Hailuo standard/pro |
| `sora_video` | Video | Sora 2 / Sora 2 Pro |
| `veo3_generate_video` | Video | Google Veo3.1 — **API dedicada `/veo/*`**, no el flujo genérico del Market |
| `veo3_extend_video` | Video | Extiende un video Veo3 existente (`/veo/extend`) |
| `wan_video` | Video | Wan texto/imagen/video |
| `wan_animate` | Video | Animación de imágenes con Wan |
| `runway_aleph_video` | Video | Runway Aleph video→video — **API dedicada `/aleph/*`**, distinta del Runway genérico |
| `infinitalk_lip_sync` | Video | Sincronización labial (lip-sync) |
| `suno_generate_music` | Audio | Música con IA (Suno) |
| `elevenlabs_tts` | Audio | Texto a voz (ElevenLabs) |
| `elevenlabs_ttsfx` | Audio | Efectos de sonido (ElevenLabs) |
| `get_task_status` | Utilidad | Consulta el progreso de una tarea (`source`: `auto`\|`common`\|`gpt4o`\|`veo3`\|`aleph`) |
| `get_veo3_1080p_video` | Utilidad | Obtiene el render en 1080p de un video Veo3 completado |
| `get_veo3_4k_video` | Utilidad | Obtiene el render en 4K de un video Veo3 completado |
| `get_download_url` | Utilidad | Convierte una URL de kie.ai en un link de descarga directa (20 min) |
| `get_credit_balance` | Utilidad | Consulta el saldo de créditos de la cuenta |

## Límites de la API

- 20 solicitudes por 10 segundos por cuenta
- Soporta 100+ tareas concurrentes
- Las URLs de resultado expiran a los 14 días

## Estructura del repositorio

```
.
├── src/
│   ├── index.ts       # Servidor MCP: registro y enrutamiento de tools
│   ├── tools.ts        # Definición de cada tool (schema Zod + mapeo a modelo kie.ai)
│   └── api.ts           # Cliente HTTP: createTask, recordInfo, y APIs dedicadas Veo3/Aleph
├── package.json
├── tsconfig.json
└── .gitignore           # Excluye node_modules/, dist/, .env
```

## Autoría y desarrollo

- **Estructura base del servidor MCP**: [neokahu/kie-ai-mcp](https://github.com/neokahu/kie-ai-mcp) v1.0.0 (MIT)
- **Corrección de bugs, enrutamiento Veo3/Aleph, incorporación de modelos flagship, y toda la documentación de este repositorio**: RF Consultoría Integral

## Licencia

Todos los derechos reservados © RF Consultoría Integral. Ver [`LICENSE`](./LICENSE).