██╗ ██╗██╗███████╗
██║ ██╔╝██║██╔════╝
█████╔╝ ██║█████╗ 
██╔═██╗ ██║██╔══╝ 
██║ ██╗██║███████╗
╚═╝ ╚═╝╚═╝╚══════╝
 C L I / M C P

🇬🇧 English · 🇪🇸 Español

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.

⚡ 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.

And the bundled CLI (kie-cli) costs zero context tokens until you call it: the agent discovers commands on demand with kie-cli --help instead of carrying schemas around. One registry, two surfaces, minimal footprint.

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.

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.

Add Kie.ai to your MCP client. Pick how many tools you want loaded:

{
 "mcpServers": {
 "kie-ai": {
 "command": "npx",
 "args": ["-y", "@felores/kie-ai-mcp-server"],
 "env": {
 "KIE_AI_API_KEY": "your-api-key-here"
 }
 }
 }
}

This makes every tool available, so every tool's schema goes into your context.

Add KIE_AI_ENABLED_TOOLS with a comma-separated list; only those tools load:

{
 "mcpServers": {
 "kie-ai": {
 "command": "npx",
 "args": ["-y", "@felores/kie-ai-mcp-server"],
 "env": {
 "KIE_AI_API_KEY": "your-api-key-here",
 "KIE_AI_ENABLED_TOOLS": "nano_banana_image,veo3_generate_video,suno_generate_music"
 }
 }
 }
}

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.

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).
• The utility tools (list_tasks, get_task_status) are always enabled and can't be disabled, they're how you track and poll your generations.

skills/kie-ai/ is a Claude Code skill that teaches agents to drive the kie-cli command (discover → generate → poll → result), including how to install the CLI if it's missing. Skills load globally, so install it into your personal skills dir (a project-local skill only triggers inside this repo):

cp -r skills/kie-ai ~/.claude/skills/kie-ai
# or symlink to keep it in sync with the repo:
ln -s "$PWD/skills/kie-ai" ~/.claude/skills/kie-ai

Then any session can generate media in plain language ("make me an image of...", "turn this photo into a video").

A unified, always-current catalog including:

• Google Veo 3: cinematic video with synchronized audio and 1080p output
• Nano Banana 2 (Gemini 3 Flash Image): fast image generation/editing with Google Search grounding
• Suno V5: music generation with realistic vocals
• Kling 3.0, Wan 2.7, Hailuo 02, ByteDance Seedance, HappyHorse, Runway Aleph, Midjourney: video generation and editing
• GPT Image 2, Flux Kontext / Flux 2, Qwen, ByteDance Seedream, Ideogram, Recraft, Topaz: image generation, editing, reframing, background removal, upscaling
• 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 .

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, kie://guides/video, kie://guides/quality: model comparison and cost/quality guides.
  • kie://tasks/active, kie://stats/usage: live view of the local task database.

{
 "tool": "nano_banana_image",
 "arguments": {
 "prompt": "A futuristic city at sunset, cyberpunk style",
 "aspect_ratio": "16:9",
 "resolution": "2K",
 "output_format": "png"
 }
}

# Generate an image, then wait for the result in one call (no manual polling)
kie-cli nano_banana_image --prompt "a red panda coding at night, neon" --resolution 2K --json
kie-cli wait_for_task --task_id <id> --json
# Music, with custom lyrics off
kie-cli suno_generate_music --prompt "Upbeat electronic, energetic" --customMode --model V5 --title "Energy Boost"
# Speech
kie-cli elevenlabs_tts --text "Welcome to the future of content creation!" --voice Rachel --model turbo

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.

export KIE_AI_API_KEY="your-api-key-here" # Get from https://kie.ai/api-key

export KIE_AI_BASE_URL="https://api.kie.ai/api/v1" # API base URL
export KIE_AI_TIMEOUT="60000" # Request timeout (ms)
export KIE_AI_DB_PATH="./tasks.db" # Task database location
export KIE_AI_CALLBACK_URL="https://your-domain.com/webhook" # Custom callback
export KIE_AI_CALLBACK_URL_FALLBACK="https://your-proxy.com/callback" # Deployment-wide default

git clone https://github.com/felores/kie-cli-mcp.git
cd kie-cli-mcp
npm install
npm run build # build all workspaces
npm run typecheck # type-check all workspaces
npm test # run the test suite

KIE_AI_API_KEY=sk-... MCP_TRANSPORT=http MCP_HTTP_PORT=3000 \
 node packages/mcp/dist/index.js
curl http://127.0.0.1:3000/health
# → {"status":"ok","transport":"streamable-http","sessions":0,"version":"3.5.0"}

The server keeps a local SQLite database of the tasks it creates and polls, persistent across restarts, used for status tracking and correct endpoint routing.

{ "tool": "list_tasks", "arguments": { "limit": 20, "status": "completed" } }

{ "tool": "get_task_status", "arguments": { "task_id": "281e5b0...f39b9" } }

Note: list_tasks reflects the MCP's local cache, tasks it has created or polled, not your full Kie.ai account history. See docs/DATABASE.md.

The server surfaces Kie.ai's response codes (it only treats code === 200 as success):

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

• docs/TOOLS.md: complete tool reference
• docs/DATABASE.md: database and task lifecycle
• docs/ADMIN.md: deployment and environment setup
• docs/INTELLIGENCE.md: smart mode detection and cost optimization

• This server (MCP or CLI): open a pull request at https://github.com/felores/kie-cli-mcp
• Kie.ai API: support@kie.ai or https://docs.kie.ai/
• API keys: https://kie.ai/api-key

Fork → feature branch → make your change (add tests if applicable) → open a PR.

MIT, see LICENSE.

See CHANGELOG.md.