⚡ kieboost-mcp

Servidor MCP (Model Context Protocol) que conecta Claude (o cualquier cliente MCP) con la API de 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 (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)

Instalación

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:

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):

{
  "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 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.