kie-mcp

kie-mcp

A comprehensive Model Context Protocol server for the kie.ai generation API. Gives Claude (and any MCP client) access to 60+ image models, 85+ video models, and 20+ audio tools with deep model intelligence built in.

Why this exists

Most MCPs are thin API wrappers. This one is different:

• Vertical profiles (NEW in 5.0) — per-domain playbooks: profile_brief returns the intake questions a professional would ask, model routing per deliverable with live costs, per-model prompt formulas, and multi-tool workflows. Profiles double as MCP prompts (/kie-art:architecture in Claude Code). Verticals (10): architecture & interiors, video game assets, advertising & marketing, web & software product imagery, film & storyboarding, product photography & e-commerce, brand & graphic design, editorial & publishing, short-form social video, and audio branding & music.

• Deep research embedded — Every major model has a research field with verdicts, prompt techniques, weaknesses, cost-efficiency analysis, and competitor comparisons. Researched by Averiguare, our model intelligence agent.

• Cost-aware — Every model has pricing in credits and USD. The MCP tells you the cheapest option for your use case.

• Smart filtering — list_models filter="lip sync" or filter="architecture" or filter="cheapest video" — searches across capability tags, descriptions, AND research fields.

• Dual-mode transport — stdio for local Claude Code, HTTP Streamable for remote Cowork/cloud usage.

What you can do with it

Just ask Claude things like:

• "Generate a brand presentation board for a perfume launch" — picks GPT Image 2 (best for text-heavy layouts)
• "Make a 10s video of fruit scarecrows defending against crows, Pixar style" — recommends Veo 3.1 or Wan 2.7
• "Generate music for a fantasy adventure game" — Suno V5
• "Lip-sync this audio to my character image" — Kling AI Avatar or Infinitalk
• "Upscale this video to 4K" — Veo 4K upscale or Topaz
• "Replace the wall color in this room photo" — Flux Kontext Pro (best for surgical edits)

Model coverage

Image (60+)

• OpenAI: GPT Image 2.5 Flare / Sunburst (NEW — 1K-4K, transparent background), GPT Image 2, GPT-4o Image, GPT Image 1.5
• Google: Nano Banana 2.1 (NEW, 4 cr), Nano Banana 2 / 2 Lite / Pro / Edit / Original, Imagen 4 (Fast/Standard/Ultra)
• Black Forest Labs: FLUX 3 Klein T2I + Edit (NEW, 1.6 cr), Flux Kontext Pro/Max, Flux 2 Pro/Flex
• ByteDance: Seedream 3.0 / 4.0 / 4.5 / 5.0 Lite
• Alibaba: Wan 2.7 Image / Image Pro
• Ideogram: v3, Character, Edit, Remix, Reframe
• xAI Grok Imagine Image 2.0 (#2 Arena T2I + edit; free segment map → region-targeted edit chain; whole-image edits of ANY uploaded image)
• ByteDance Seedream 5.0 Pro (NEW — T2I/I2I + layer decomposition: split any image into layer files)
• Qwen Image 3.0 / 3.0 Pro (NEW — seed, negative prompts, 2K at the 1K price on standard)
• Qwen Image 2.1 (NEW — transparent background, mask inpainting, 10-ref compositing)
• Others: Qwen/Qwen2, Z-Image, Grok Imagine 1.x, Recraft, Topaz

Video (85+)

• Google Veo 3.1: Quality / Fast / Lite (T2V + I2V), Extend, 1080p/4K upscale
• Alibaba HappyHorse: 1.1 (NEW — T2V/I2V/R2V with native audio + 7-language lip-sync), 1.0 (T2V/I2V/R2V/Video Edit)
• ByteDance Seedance: 2.5 (30s single takes, 1080p, draft→1080p upgrade) / 2.0 / 2.0 Fast / 2.0 Mini (1.5 Pro retired upstream Oct 2026)
• Kuaishou Kling: 4.0 (NEW — reference-to-video with named @subjects/voices/video refs, keyframe-to-video, 3-30s), 3.0 Omni "O3" (NEW — per-shot multi_prompt scripting, 4K, video Transformation), 3.0, 3.0 Turbo, 2.6, V2.5 Turbo, V2.1 Master/Pro/Standard, AI Avatar
• Alibaba Wan: 3.0 + 3.0 Prime (NEW — unified prompt-or-media, audio), 2.7 (T2V/I2V/Edit/R2V), 2.6, 2.5, 2.2 Turbo, Animate
• Google Gemini Omni: Video + 1.1 Flash (NEW — first→last-frame mode, 360p-4K; image/voice/video/character references)
• MiniMax Hailuo: H3 (NEW — 2K + native stereo audio, image+video+audio references, first→last-frame I2V), 2.3 Pro/Standard, 02 Pro/Standard
• xAI Grok Imagine: Video 1.5 preview (NEW — I2V with native audio, cheapest audio video), T2V, I2V, Upscale, Extend
• Avatar / lip-sync: OmniHuman 2.0 (NEW — 14 cr/s, up to 5-minute audio), OmniHuman 1.5 (NEW — audio-driven full-body avatar + free subject-detection + human-identification utilities), Volcengine Video Lip-Sync (NEW — re-dub existing footage), Kling AI Avatar, Infinitalk
• PixVerse V6 / V6 Max (V6 Max NEW: higher-quality T2V/I2V): T2V, I2V (viral templates), Transition (first→last morph), Fusion R2V (@ref_name), Extend — budget all-rounder with native audio
• Runway: Aleph, Aleph Edit, Extend
• Others: ByteDance V1 Pro/Lite, Topaz upscale

Audio (20+)

• Suno: Music Gen, Extend, Cover, Add Instrumental/Vocals, Replace Section, Lyrics, Sounds, Sound Effects, MIDI, Music Video, Cover Art, Mashup, Persona, Timestamped Lyrics, Boost Style, Vocal Separation, WAV, Custom Voice cloning (experimental)
• ElevenLabs: TTS (Turbo 2.5 + Multilingual V2), Text-to-Dialogue V3, Audio Isolation, Speech-to-Text
• Google Gemini TTS (NEW): style-directed speech, 30 voices, 2-speaker dialogue, inline tone tags — ~4.2 cr/min

Utility

• File upload (URL or base64)
• Veo Extend, 1080p Upscale, 4K Upscale
• Runway Extend
• Task status, credit check, raw asset listing

Installation

Prerequisites

• Node.js 18+
• A kie.ai API key from kie.ai/api-key

Setup

git clone https://github.com/YOUR_USERNAME/kie-mcp.git
cd kie-mcp
npm install

Run as stdio MCP (Claude Code, Claude Desktop)

Add to your Claude config (~/.claude.json for Claude Code, or your MCP client's equivalent):

{
  "mcpServers": {
    "kie-art": {
      "command": "node",
      "args": ["/absolute/path/to/kie-mcp/server.mjs"],
      "env": {
        "KIE_API_KEY": "your-kie-ai-api-key",
        "KIE_PROJECT_ROOT": "/optional/path/for/outputs"
      }
    }
  }
}

Or use the Claude Code CLI:

claude mcp add -s user kie-art /usr/bin/env -- KIE_API_KEY=your-key node /path/to/server.mjs

Run as HTTP MCP (Cowork, remote clients)

HTTP mode requires a bearer token and listens on 127.0.0.1 by default.

export KIE_MCP_AUTH_TOKEN=$(openssl rand -hex 32)
KIE_API_KEY=your-key node server.mjs --http --port=3100

Configure your MCP client with the URL and the token:

{
  "mcpServers": {
    "kie-art": {
      "type": "http",
      "url": "http://127.0.0.1:3100/mcp",
      "headers": { "Authorization": "Bearer <your KIE_MCP_AUTH_TOKEN>" }
    }
  }
}

To reach it remotely, put it behind a tunnel (ngrok / Cloudflare Tunnel) or a reverse proxy. The server stays on loopback and the tunnel forwards to it. Add the tunnel's hostname to KIE_MCP_ALLOWED_HOSTS. Treat the token like a password: anyone who has it can spend your kie credits and upload media files from the server's disk.

Security note (5.2.2): earlier versions ran HTTP mode on 0.0.0.0 with no authentication and Access-Control-Allow-Origin: *. Any web page open in your browser, or anyone who had the tunnel URL, could call the tools, including reading local files through upload_file. Upgrade if you use --http.

Environment variables

Variable	Required	Purpose
KIE_API_KEY	yes	Your kie.ai API key
KIE_PROJECT_ROOT	no	Server-wide default for where generated files are saved (default: server cwd; files go to $KIE_PROJECT_ROOT/kie/assets/raw/). Per-call download_dir (absolute path) on any file-writing tool overrides this
KIE_MCP_PORT	no	Port for HTTP mode (default: 3100)
KIE_SUNO_API	no	legacy sends Suno tools to kie's old Suno endpoints. Default since 5.5.0 is kie's new market API (ai-music-api/*), which reports the actual credits charged. MIDI, mashup and voice cloning always use the old endpoints
KIE_ELEVENLABS_ENABLED	no	1 re-enables the ElevenLabs tools (paused since 5.4.0 while kie's ElevenLabs integration fails)
KIE_MAX_CREDITS_PER_CALL	no	Default spending cap per tool call, in credits. Calls whose estimate exceeds it are refused before submission; a per-call max_credits overrides it
KIE_MCP_AUTH_TOKEN	HTTP mode	Bearer token HTTP clients must send (Authorization: Bearer …). The server refuses to start in HTTP mode without it
KIE_MCP_HOST	no	HTTP bind address (default 127.0.0.1). Set 0.0.0.0 only inside a container or behind a firewall
KIE_MCP_ALLOWED_HOSTS	no	Comma-separated extra Host header names to accept (e.g. your tunnel hostname). On loopback, localhost names are always accepted; other hosts are rejected to block DNS rebinding
KIE_MCP_ALLOWED_ORIGINS	no	Comma-separated browser origins allowed to call the server (CORS). Requests with any other Origin header are rejected. Non-browser MCP clients send no Origin and are unaffected
KIE_CALLBACK_URL	no	Callback URL sent with Suno generation requests (kie.ai requires the field; results are fetched by polling regardless). Defaults to an inert placeholder — set this only if you want to receive the callbacks yourself
KIE_MAX_CONCURRENT	no	Max simultaneous task-creation calls (default 4). Excess parallel generations queue inside the server instead of hitting kie.ai's rate limits — parallel tool calls are safe
KIE_POLL_BUDGET_IMAGE / _VIDEO / _AUDIO / _SPEECH	no	Blocking-mode polling budget per tool category, in seconds (defaults: 600 / 900 / 300 / 300). Per-call max_wait_seconds takes precedence. For long generations prefer wait: false (async mode): the tool returns the task_id immediately; poll with check_task, fetch with download_result

Tools available

generate_image, generate_video, generate_music, generate_sfx,
generate_tts, generate_gemini_tts, generate_dialogue, generate_sounds, generate_lyrics,
generate_persona, generate_mashup, generate_cover_art,
generate_midi, create_music_video,
prepare_voice_clone, create_voice_clone, regenerate_voice_clone,
create_omni_voice, create_omni_character,
extend_music, cover_audio, upload_extend_audio,
add_instrumental, add_vocals, replace_section,
convert_to_wav, separate_vocals, boost_style,
get_timestamped_lyrics, audio_isolation, speech_to_text,
profile_brief,
list_models, check_task, list_tasks, check_credits, spend_report,
download_result, list_raw_assets, upload_file,
grok_segment_map, grok_image_edit, seedream_layer_decompose,
veo_extend, veo_upscale_1080p, veo_upscale_4k, runway_extend

Cost control

kie bills per call, and a few calls are expensive (1080p/4K video, layer splits, 1080p draft upgrades). Every paid tool takes two optional parameters:

• estimate_only: true returns the estimated credits from published rates, including resolution/size tiers and video duration, without submitting anything.
• max_credits: N refuses to submit when the estimate exceeds N. Set KIE_MAX_CREDITS_PER_CALL to apply a default cap to every call.

generate_video { model: "bytedance/seedance-2-5", model_options: { resolution: "1080p", duration: 10 }, estimate_only: true }
→ 💰 ~1580 credits (~$7.90) — 158 cr/s × 10s. Nothing was submitted.

spend_report shows where the credits went. It totals the server's task history over the last N days, by model or by day, using the actual amounts kie charged (it looks up any missing ones), and lists failed tasks separately.

Smart model recommendations

Try these queries in any MCP client:

list_models filter="reasoning"          # GPT-4o, Nano Banana, GPT Image 2
list_models filter="lip-sync"           # OmniHuman 1.5, Volcengine, Kling Avatar, HappyHorse 1.1
list_models filter="multi-shot"         # Kling 3.0/Turbo
list_models filter="cheapest video"     # Grok Imagine 1.5, Wan Flash
list_models filter="alibaba"            # HappyHorse 1.0/1.1 family
list_models filter="best visual quality" # Veo Quality, Seedance 2.0
list_models filter="text rendering"     # Ideogram v3, GPT Image 2
list_models filter="character"          # Ideogram Character, Kling AI Avatar

Architecture

server.mjs                      # Transport, helpers, tool handlers (~2700 lines)
├── createMcpServer()           # Factory for stdio + HTTP modes
├── Tool handlers               # generate_*, list_*, etc.
└── helpers                     # polling, recovery, pricing, validation, download

data/                           # Pure data, imported (and re-exported) by server.mjs
├── registry-image.mjs          # MODEL_REGISTRY — image models (47+)
├── registry-video.mjs          # VIDEO_MODEL_REGISTRY — video models (80+)
├── registry-audio.mjs          # AUDIO_TOOLS_REGISTRY — audio tool metadata
├── pricing.mjs                 # PRICING, PRICING_ESTIMATED, PROMPT_CAPS
└── voices.mjs                  # ELEVENLABS_VOICES catalog

The registries and pricing live in data/*.mjs so model-catalog changes are reviewable diffs instead of edits buried in a 5000-line file; server.mjs imports and re-exports them (tests and downstream keep importing from server.mjs).

Each model entry has:

• name, description, capabilities (tags), pricing (credits)
• aspectRatios, options (with types and defaults)
• buildBody / buildInput (request builders)
• research (Averiguare verdicts, prompt techniques, weaknesses, comparisons, sources)

Development

npm run check   # node --check server.mjs (syntax)
npm test        # offline unit tests for the pure helpers (test/*.test.mjs)
npm run smoke   # live end-to-end over MCP stdio — needs KIE_API_KEY
                # (spends ~0 credits; uses the free subject-detection model)

server.mjs guards its side effects behind a main-module check, so it can be imported by tests (test/unit.test.mjs) to exercise the pure helpers without starting a server. test/harness.mjs is a reusable stdio JSON-RPC client for driving the real server in smoke/integration checks. CI (.github/workflows/ci.yml) runs the syntax check + unit tests on Node 20 and 22 for every push and PR.

Live check (run this weekly)

npm run live-check   # KIE_API_KEY from env, else ~/.claude.json kie-art

Runs the whole maintenance routine in about 2 minutes and writes live-check-report.md:

1. Docs-index diff: docs.kie.ai pages added or removed since the last run. This is the most reliable new-model signal.
2. Drift watch with live slug probes: price drift, paused/removed models, catalog changes.
3. Watch list: real calls to models that were failing upstream (e.g. ElevenLabs), so you know when to re-enable them. Failures cost 0 credits.
4. npm audit summary.

Run it from your own machine. GitHub-hosted runners can't fetch kie.ai pages, so the scheduled workflow below only reports that it's blind.

Drift watch

kie.ai changes things without notice — advertised prices, model availability, even API shapes. .github/workflows/drift-watch.yml runs scripts/drift-watch.mjs weekly (and on demand) to scan for it: paused/removed slugs, pricing that no longer matches the PRICING table, and new models in kie's catalog. Findings land in a single rolling GitHub issue. Add a KIE_API_KEY repo secret to enable the per-slug liveness probes (0 credits — empty-input validation errors); the pricing and new-model scans need no secret. Run locally with node scripts/drift-watch.mjs.

Releasing

Releases are automated by .github/workflows/release.yml. To cut a release:

1. Bump the version in package.json, server.json (both the top-level version and packages[0].version), and server.mjs (SERVER_INFO + the /health handler), and add a ## [X.Y.Z] section to CHANGELOG.md. Merge to main.
2. Tag and push:

   git tag vX.Y.Z && git push origin vX.Y.Z
   

The workflow verifies the tag matches every in-repo version string, publishes to npm with provenance (NPM_TOKEN repo secret), and creates the GitHub Release using the matching CHANGELOG section as the notes. A tag whose version doesn't match the code fails fast without publishing. workflow_dispatch is an emergency manual publish of the current package.json version.

Credits

• Built with the MCP TypeScript SDK
• Powered by kie.ai — affordable unified API for 100+ AI models
• Model intelligence by Averiguare — "No sabes hasta que averiguas — y averiguo en todas partes."

License

MIT