One API for state-of-the-art AI media models (Veo 3, Nano Banana, Suno, Kling, Flux, ElevenLabs, Seedance and more), exposed as both an MCP server and a standalone CLI generated from one shared tool registry. Generate video, images, music and speech from Claude, Codex, OpenCode, Pi-mono, or any agentic harness, or straight from your terminal.
MCP server for Kie.ai APIs: image, video, music and speech generation across Nano Banana, Veo3, Suno, ElevenLabs, ByteDance, Qwen, Runway, Midjourney, Wan, MiniMax H3, Kling, GPT Image 2, Flux Kontext, Recraft, Ideogram, Topaz, HappyHorse and more.
2026-11-17
星數
—
工具
—
可用率
—
⚡ Token-efficient by design
An MCP server injects every tool's schema into your model's context on every turn: with a catalog this large, that's a lot of tokens spent on tools you may never call.
This server fixes that: load only the tools you actually use with KIE_AI_ENABLED_TOOLS (or whole categories with KIE_AI_TOOL_CATEGORIES). Your context stays lean and you pay for exactly the surface you need, no more, no less.
Two ways to use it (one shared core)
The MCP server and the CLI are generated from the same tool registry, so both expose the exact same models and install independently:
MCP server: @felores/kie-ai-mcp-server, for Claude Desktop and other MCP clients. See Quick Start below.
CLI: @felores/kie-cli (binary kie-cli), for the terminal, no MCP client needed: npm i -g @felores/kie-cli, then kie-cli --help. See packages/cli/README.md.
OpenAI transport: @felores/kie-ai-openai-server, a loopback HTTP server for selected image/video models. Version 0.8 upgrades GPT Image to 2.5 Flare, Qwen to Qwen3, and HappyHorse to 1.1 while preserving compatibility IDs. See docs/openai-transport.md.
The MCP server runs locally over stdio by default, and can also run as a remote HTTP service (Streamable HTTP) so one shared instance serves many clients over the network. It ships with a Dockerfile and a Coolify compose file for one-step self-hosting (deploy guide). See the Remote / HTTP transport section below.
Secure reference uploads
upload_file sends validated Base64 directly to Kie. The CLI can also read a
local path only beneath explicit KIE_CLI_UPLOAD_ROOTS. Arbitrary URL import
is intentionally unavailable.
upload_widget renders a minimal MCP Apps file picker when the host supports
ui:// resources.
Remote operators may enable temporary capability storage with
KIE_MCP_PUBLIC_BASE_URL. Upload minting stays behind authenticated MCP;
one-use upload URLs stay in app metadata. Only an opaque media_id reaches
model content; the server resolves it to Kie immediately before submission.
See the HTTP deployment guide.
Safe media workflow
Version 4 makes cost control a server-side workflow instead of an agent instruction:
Surface
Prepare
Human approval
Submit
MCP
prepare_media_generation
Host elicitation.form confirmation
submit_media_generation
CLI
prepare_media_generation
--approve <plan-id>
submit_media_generation
Preparation validates one to six requests, resolves model settings and policy defaults, records pricing as exact only for verified formulas and unknown otherwise, and creates no provider task. A plan is persistent, expires after 15 minutes by default, is bound to its MCP server session, and can be submitted only once. See Media planning and approval for the complete flow.
🚀 Quick Start
Requires Node.js >= 20 to run the MCP server.
Add Kie.ai to your MCP client. Pick how many tools you want loaded:
This loads only those tools (plus the always-on utility tools), keeping your context lean.
Get your free API key:kie.ai/api-key. No callback URL setup required, the server handles it automatically.
For Claude Desktop: add this to ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Also works with Cursor, Windsurf, VS Code, Claude Code, OpenCode, Droid, and others.
🎛️ More ways to filter
Same idea, different env vars (inside the env block, or as shell exports for the CLI, e.g. export KIE_AI_ENABLED_TOOLS="nano_banana_image,veo3_generate_video"):
// Load whole categories instead of naming each tool
"KIE_AI_TOOL_CATEGORIES": "image,video"
// Or load everything EXCEPT some tools
"KIE_AI_DISABLED_TOOLS": "midjourney_generate,runway_aleph_video"
Categories:image, video, audio, utility.
Priority:ENABLED_TOOLS > TOOL_CATEGORIES > DISABLED_TOOLS > all tools (default).
Utility tools, including task tracking and upload helpers, are always enabled and cannot be disabled.
Official MCP Tasks are experimental and opt-in: set KIE_AI_MCP_TASKS=true to declare the tasks capability, per-tool execution.taskSupport, and the task-mode tools/call surface. The published MCP SDK still negotiates at most 2025-11-25, so task-mode calls are currently refused with a clear error instead of running; the surface activates once the SDK negotiates the 2026-07-28 revision. Legacy get_task_status / list_tasks / wait_for_task remain available in all modes.
MCP hides and rejects direct image, video, and audio tool calls by default. Use prepare_media_generation, host approval elicitation, and submit_media_generation instead. KIE_AI_ALLOW_DIRECT_GENERATION=true is the explicit legacy bypass when you intentionally disable these approval safeguards. Filtering still controls which generation tools can be plan targets.
MCP hides and rejects direct image, video, and audio tool calls by default. Use prepare_media_generation, host approval elicitation, and submit_media_generation instead. KIE_AI_ALLOW_DIRECT_GENERATION=true is the explicit legacy bypass when you intentionally disable these approval safeguards. Filtering still controls which generation tools can be plan targets. Use prepare_media_generation, host approval elicitation, and submit_media_generation instead. KIE_AI_ALLOW_DIRECT_GENERATION=true is the explicit legacy bypass when you intentionally disable these approval safeguards. Filtering still controls which generation tools can be plan targets.
🤖 Agent skill (optional)
skills/generate-media/ is the canonical agent workflow. It requires a persisted plan, displays resolved settings and verified pricing state, then waits for explicit approval before task submission. skills/kie-ai/ is a migration pointer only. Skills load globally, so install the canonical skill into your personal skills dir:
cp -r skills/generate-media ~/.claude/skills/generate-media
# or symlink to keep it in sync with the repo:
ln -s "$PWD/skills/generate-media" ~/.claude/skills/generate-media
Then any session can prepare media in plain language ("make me an image of...", "turn this photo into a video") and request approval before a paid task starts.
Media planning and approval
Use list_models to search source-backed capabilities, then prepare one to six requests in a single persisted plan. Preparing validates target schemas and applies safe defaults, but never calls a Kie generation endpoint.
{
"tool": "prepare_media_generation",
"arguments": {
"items": [
{ "tool": "nano_banana_image", "args": { "prompt": "A red panda coding at night" } }
]
}
}
For MCP clients that advertise and handle the elicitation.form capability, preparation shows the complete resolved plan and price summary in a host confirmation form. Only an accepted form with confirm: true records the plan as approved. Declined, cancelled, unconfirmed, and unsupported elicitations leave the plan prepared and unapproved. Submit only the resulting approved plan ID:
The CLI has no MCP host. It requires an explicit --approve <plan-id> value matching --planId; this atomically changes a prepared plan to approved before submission.
Pricing refresh is read-only by default: npm run pricing:refresh reports the tracked source evidence freshness and does not fetch, scrape, or write. npm run pricing:refresh -- --apply is an explicit metadata-only boundary. It is an intentional no-op without eligible validated formula proposals; with --proposals <file>, it can record the proposed deterministic credits formula plus its source URL, fingerprint, verification date, scope, and test evidence in the rate-card evidence manifest. It never edits executable formulas or derives USD conversions automatically.
Plans are persisted in the local SQLite database and move atomically from prepared to approved, submitting, and then submitted or failed. They expire after 15 minutes by default, cannot be modified, and cannot be submitted twice. The request hash detects accidental plan mutation only. An MCP plan is also bound to the server instance that prepared and approved it, so another HTTP session cannot submit it. A submitted batch creates no more than four provider tasks concurrently. Exact credit quotes exist only for verified request dimensions; all other requests are unknown. No USD conversion is assumed.
Models
A unified, always-current catalog organized by job:
Cinematic generation with synchronized audio and 1080p output
veo3_generate_video
Gemini Omni
Videos with reusable characters and voices
gemini_omni
MiniMax H3 (Hailuo 03)
Text, first/last-frame, and multimodal reference-to-video
hailuo_video
Wan 3.0 / Prime and HappyHorse 1.1
Multimodal references and video generation
wan_video, happyhorse_video
Video editing and avatars
Runway Aleph: video-to-video transformation and editing
Midjourney and Grok Imagine: image-to-video, stylized generation, and Grok Imagine Image 2.0 image editing
Wan Animate: character animation and replacement
OmniHuman 1.5, Kling Avatar, and InfiniTalk: talking avatars and lip sync
Image generation and editing
Nano Banana 2 / Lite, GPT Image 2.5, Seedream 5 Pro / Flash, Qwen3 / Pro, Wan 2.7 Image / Pro, Flux Kontext / Flux 2, and Z-Image: generation and image editing
Ideogram, Recraft, and Topaz: reframing, background removal, and upscaling
Audio
Suno V6 / Mini / Wild: music generation with lyrics, personas, media references, and custom duration control
ElevenLabs: text-to-speech and sound effects
Each tool features smart mode detection: one tool handles generate / edit / upscale based on the parameters you pass.
The complete, current list is always available: run kie-cli --help (and kie-cli <tool> --help for a tool's flags), or see docs/TOOLS.md.
MCP resources & prompts
Beyond tools, the MCP server exposes (all generated from the registry, so they never drift):
Prompts (slash commands in your client): /image and /video: guidance for picking and driving the right model.
Resources:
kie://tools/<name>: a Markdown reference for each tool (parameters, types, defaults), generated from its schema.
kie://guides/image-models-comparison, kie://guides/video-models-comparison, kie://guides/quality-optimization: model comparison and cost/quality guides.
kie://tasks/active, kie://stats/usage: live view of the local task database.
Exact credit formula for ByteDance Seedance 2.5 without reference video: 28, 63, and 158 credits per second at 480p, 720p, and 1080p, multiplied by the generated duration.
What's new in MCP 5.4.0
Exact credit formulas for Qwen z-image (0.8 per image), Recraft Remove Background (1 per image), and Wan 2.7 Image (4.8 standard and 12 Pro, per image).
What's new in MCP 5.3.2
GPT Image 2.5 now quotes 2K at 10 credits and 4K at 16 credits per image, and image-to-image at the same per-resolution price. 1K stays at 6 credits.
What's new in MCP 5.3.1
GPT Image 2.5 Flare and Sunburst at 1K now quote an exact price: 6 credits per image. 2K, 4K, and image-to-image remain unknown.
What's new in MCP 5.3.0
The GPT Image tool is now gpt_image. The model is still GPT Image 2.5 (Flare and Sunburst). Update KIE_AI_ENABLED_TOOLS and any saved plan that names the old gpt_image_2.
What's new in MCP 5.2.0
Suno V6/Mini/Wild, GPT Image 2.5 Flare/Sunburst, Seedream 5 Pro/Flash and layers, Qwen3/Pro, and HappyHorse 1.1 replace retired provider versions.
wan_video adds Wan 3.0 Prime. New wan_image supports Wan 2.7 Image/Pro, up to nine references, sequential output, palettes, and bounding-box editing.
Shared core changes ship in CLI 0.10 and selected OpenAI adapters in transport 0.8. Historical task polling and transport aliases remain; old provider generation routes are removed. Unverified pricing remains unknown.
Migration examples:
kie-cli suno_generate_music --customMode --instrumental --model V6 --style "Ambient piano" --title "Quiet"
kie-cli gpt_image --model sunburst --prompt "A glass perfume bottle" --background transparent
kie-cli bytedance_seedream_image --version 5-flash --size 1.5K --prompt "A botanical poster"
kie-cli bytedance_seedream_image --version 5-pro --image_url https://example.com/product.png
kie-cli qwen_image --model qwen3-pro --resolution 2K --prompt "A product photo"
kie-cli happyhorse_video --image_urls https://example.com/scene.png --duration 5
kie-cli wan_video --model wan/3-0-video-prime --prompt "A mountain lake at sunrise"
kie-cli wan_image --model wan/2-7-image-pro --resolution 4K --n 1 --prompt "A city map"
Suno prompt-only non-custom requests now fail validation. Qwen editing uses image_urls; retired inference controls are rejected. Seedream Flash uses size, Pro uses quality, and one image_url selects layers. See the current endpoint contracts.
MCP 5.1
Wan 3.0.wan_video now uses the unified wan/3-0-video model with
text, first/last frames, up to 10 image references, 5 video references,
5 audio references, documents, webpages, native audio, and 2-30 second clips.
Shared release. The same Wan 3.0 contract ships in CLI 0.9 and OpenAI
transport 0.7. The OpenAI route accepts kie-wan-3-0-video and keeps
kie-wan-2-7-video as a compatibility alias.
MCP 5.0 foundation
Built on the SDK v2 packages (@modelcontextprotocol/server,
@modelcontextprotocol/node) with Node >= 20 and zod v4:
Dual protocol era. The server negotiates the protocol version per client:
2025-era clients keep working unchanged, while the 2026-07-28 vocabulary
(server/discover, cache hints, extensions, structured schemas, tasks) is
served as soon as the SDK lifts its negotiation cap.
Structured results. Failed tool calls arrive as isError: true with
structured error content; generation, upload and planning tools expose
structuredContent (task_id, media_id, plan_id) and advertise
outputSchema in tools/list.
Modern input schemas. Tool inputSchema is generated as JSON Schema
2020-12, the dialect MCP 2026-07-28 targets.
MRTR plan approval. On 2026-era hosts approval is a multi-round-trip
input_required flow; 2025-era hosts keep the push-style elicitation.
server/discover + cache hints + extension negotiation. The server
answers discovery with its supported versions, capabilities and
instructions, and advertises the MCP Apps extension that gates the upload
widget resource.
Official MCP Tasks (opt-in).KIE_AI_MCP_TASKS=true exposes the tasks
capability and task-mode tools/call runs backed by an in-process engine
mirrored to the local SQLite database; legacy get_task_status /
list_tasks / wait_for_task remain available in all modes.
Examples
MCP (prepare, approve, submit)
Prepare the paid request first. This does not start generation:
The MCP host then presents the returned plan, resolved settings, and price summary with elicitation.form. Approve that host form with confirm: true; the approved response includes a planId. Then submit that approved plan:
Do not call paid media tools directly from MCP. KIE_AI_ALLOW_DIRECT_GENERATION=true is only the explicit legacy bypass.
CLI
# 1. Prepare one or more paid requests. This creates no provider task.
kie-cli prepare_media_generation \
--items '[{"tool":"nano_banana_image","args":{"prompt":"a red panda coding at night, neon","resolution":"2K"}}]' \
--json
# 2. Review the returned plan, then explicitly approve and submit it.
kie-cli submit_media_generation \
--planId <prepared-plan-id> \
--approve <prepared-plan-id> \
--json
# 3. Wait for a returned task ID in one call.
kie-cli wait_for_task --task_id <id> --json
# Other supported jobs use the same prepare -> approve -> submit flow.
# The raw generation commands below remain lower-level compatibility APIs.
kie-cli suno_generate_music --style "Upbeat electronic, energetic" --customMode --instrumental --model V6 --title "Energy Boost"
kie-cli elevenlabs_tts --text "Welcome to the future of content creation!" --voice Rachel --model turbo
Use prepare_media_generation for any paid CLI job when you need approval, quotes, defaults, batch control, or replay protection. The raw commands remain available for scripts that deliberately own their own safety boundary. Generation is asynchronous: tools return a task_id. Wait for it in a single call with wait_for_task (it polls Kie for you and returns the final URLs when ready), or check once with get_task_status and browse recent work with list_tasks. Add --json to the CLI for machine-readable output.
In an MCP client, wait_for_task keeps the tool call open and streams notifications/progress until the result is ready, so the model gets the URLs without looping. For long jobs (video), enable resetTimeoutOnProgress with a generous maxTotalTimeout in your client so the call is not cut off at the default timeout.
Configuration
Required
export KIE_AI_API_KEY="your-api-key-here" # Get from https://kie.ai/api-key
See docs/ADMIN.md for Docker, Kubernetes and Systemd examples.
git clone https://github.com/felores/kie-cli-mcp.git
cd kie-cli-mcp
npm install
npm run check # Biome: format + lint + import organization
npm run format # apply Biome formatting
npm run build # build all workspaces
npm run typecheck # type-check all workspaces
npm test # run the test suite
This is an npm-workspaces monorepo: packages/core (private shared registry, bundled into the others), packages/mcp (@felores/kie-ai-mcp-server) and packages/cli (@felores/kie-cli). To add a model, run npm run add-tool -- <name> <category> and both surfaces pick it up. For the dev server with auto-reload: npm run dev -w @felores/kie-ai-mcp-server.
The server defaults to stdio (one local process per client). It can also run
as a remote HTTP service over Streamable HTTP. Since v5.0.0 it is built
on the MCP SDK v2 packages and serves both 2025-era and 2026-07-28 clients by
protocol negotiation.
Why use it:
One shared instance for many clients — host it once, connect your whole
team or several agents over the network instead of spawning a local process each.
Deploy anywhere — runs as a container on any host or PaaS (Dockerfile +
Coolify compose included), behind your own TLS/proxy.
Centralized config & task history — a single API key and one shared SQLite
task DB, so generations are tracked in one place.
Secured by default off-loopback — bearer-token auth and Host-allowlist
(DNS-rebinding) protection, with an open /health endpoint for uptime probes.
Zero disruption — stdio stays the default; HTTP is purely opt-in.
Docker + Coolify deployment and a client-connection walkthrough are in
docs/DEPLOY_HTTP.md.
Task management
The server keeps a local SQLite database of prepared plans and tasks, persistent across restarts, used for approval safety, status tracking, and correct endpoint routing.
Note: list_tasks reflects the MCP's local cache, tasks it has created or polled, not your full Kie.ai account history. When a provider status response includes creditsConsumed, it is returned as actual task usage, separately from a plan quote. See docs/DATABASE.md.
Error handling
The server surfaces Kie.ai's response codes (it only treats code === 200 as success):
Code
Meaning
200
Success
400
Content policy violation / English prompts only
401
Unauthorized (invalid API key)
402
Insufficient credits
404
Resource not found
422
Validation error / record is null
429
Rate limited
455
Service maintenance
500
Server error / timeout
501
Generation failed
Troubleshooting
"Unauthorized": verify KIE_AI_API_KEY is set and valid at kie.ai/api-key.
"Task not found": tasks may expire after ~14 days; check the task id.
Generation failures: check content-policy compliance, English prompts, and sufficient credits.