AGENT SKILLS · LOCAL MCP · CLI

One CLI & MCP for
200+ AI models.

Give Claude Code, Cursor, Codex, and Gemini CLI live KIE schemas, per-task catalog price checks, and zero-dependency media generation—straight from your repo.

bash / zsh · 2 lines
export KIE_API_KEY="your_api_key"
npx skills add https://kie.ai
claude · ~/shop-web
kie-models + MCP
› Generate a 2K studio product shot of a faceted perfume bottle with Kling Image 4.0 under 15 credits, save to ./public/perfume.png
0.4s · Reading live schema /api/v1/models/kling-4-0/image/schema
0.8s · Catalog price check: 2k = 11.3 credits ≤ --max-credits 15
1.2s · Submitted createTask 0ba8c332…
38.4s · Completed · 11.3 credits consumed
Saved ./public/perfume.png (5.38 MB · 2048×2048)
01

Claude Code

Auto-discovered via npx skills + /claude/v1/messages

02

Cursor & Windsurf

Local non-blocking stdio MCP server (6 tools)

03

OpenAI Codex CLI

Skills + /codex/v1/responses wire support

04

Gemini CLI

Skills + native /gemini/v1beta streaming

01 · WORKFLOWS & MCP

Works where you already write code.

Pick your coding agent or IDE below. Terminal agents load SKILL.md on demand; desktop apps connect to kie-cli.mjs mcp over standard input/output.

Install once per project or globally with -g. Claude Code automatically loads kie-models when you ask for images, videos, audio, or model pricing.

claude · ~/storefront
$ npx skills add https://kie.ai

> Generate a 16:9 hero banner for a matte black GaN desktop charger
  using Kling Image 4.0 at 2k under 15 credits, save to ./public/hero.png

  ● Skill(kie-models)
  ├─ node kie-cli.mjs doc kling-4-0/image
  ├─ node kie-cli.mjs run kling-4-0/image \
       --max-credits 15 \
       --input '{"prompt":"Matte black GaN desktop charger...","resolution":"2k","aspect_ratio":"16:9"}' \
       --out ./public/hero.png
  └─ ✓ Saved ./public/hero.png (taskId: 0ba8c332…, 11.3 credits)
02 · ENGINEERED FOR AUTONOMOUS AGENTS

Pre-flight price checks & timeout-safe MCP.

Autonomous agents retry aggressively and pass unvalidated paths unless the tool layer enforces clear boundaries. kie-cli.mjs builds three safeguards into the runtime:

Per-task catalog price check (--max-credits)

Narrows live catalog rows by your input hints (resolution, mode, duration, count) and checks the conservative upper bound before calling createTask. Exits locally with code 3 if exceeded.

Non-blocking stdio & two-phase 20s polling

Answers host ping checks concurrently and returns { taskId, state: "generating" } within 20s on long video jobs—staying inside typical ~60s desktop tool timeouts so the agent polls kie_task_status instead of resubmitting.

Workspace-jailed downloads (wx)

MCP outPath is resolved with fs.realpathSync inside KIE_OUTPUT_DIR prior to task creation and written with flag: "wx" so existing files are never overwritten.

Pre-flight check · exit code 30 credits spent
$ node kie-cli.mjs run veo-3-1 \
    --input '{"prompt":"Aerial coastline","mode":"Quality-4k"}' \
    --max-credits 50

[kie] Error: Per-task price check blocked request:
  "veo-3-1" can cost up to 400 credits in the catalog
  for these parameters, which exceeds --max-credits 50.
  Nothing was sent.
$ echo $?
3

# Switch to Lite-1080p (35 credits <= 50) -> proceeds cleanly:
$ node kie-cli.mjs run veo-3-1 \
    --input '{"prompt":"Aerial coastline","mode":"Lite-1080p"}' \
    --max-credits 50 --out ./coast.mp4
✓ Saved ./coast.mp4 (35 credits)
03 · COMMAND REFERENCE

Every command on one screen.

Requires Node.js 18+ with zero external packages. Exit codes: 0 ok, 1 API / runtime error, 2 invalid flag, 3 --max-credits pre-flight block.

ENVIRONMENT VARIABLES
KIE_API_KEY
Bearer token from kie.ai/api-key
KIE_MAX_CREDITS
Default per-task catalog ceiling for CLI & MCP
KIE_OUTPUT_DIR
Sandbox directory for MCP file writes (defaults to cwd)
list [--task T] [--provider P] [--q kw] [--json]
Query live models on KIE (uses /api/v1/models with key, or public catalog without key).
doc <model_id_or_slug>
Print inline OpenAPI 3.1 JSON schema or /model/<slug>.md parameter specification.
price [keyword] [--json]
Query live catalog credit & USD unit prices (no API key required).
balance [--json]
Read remaining credits on KIE_API_KEY via GET /api/v1/chat/credit.
run <model_id> --input '{...}' [--max-credits N] [--out path]
Pre-check catalog upper bound, submit createTask, poll recordInfo, and download output.
status <task_id> [--wait sec] [--out path]
Check or resume polling an existing taskId without resubmitting.
mcp
Start non-blocking JSON-RPC 2.0 stdio MCP server (6 tools for Cursor / Claude Desktop).
04 · FAQ

Frequently asked questions.

Explore individual model endpoints in the API Market or compare unit rates on Pricing.

How do I set up the KIE MCP Server in Cursor, Windsurf, or Claude Desktop?

+

Download kie-cli.mjs (via npx skills add https://kie.ai -g or curl -fsSL https://kie.ai/cli/kie-cli.mjs -o ~/.kie/kie-cli.mjs) and add "command": "node" with args ["/path/to/kie-cli.mjs", "mcp"] and env KIE_API_KEY in mcp.json or claude_desktop_config.json. It runs locally over stdio with zero npm dependencies and exposes kie_list_models, kie_model_spec, kie_pricing, kie_credit_balance, kie_submit_task, and kie_task_status.

What is the difference between Agent Skills and the Local MCP Server?

+

Agent Skills (npx skills add https://kie.ai) drop compact SKILL.md instructions and kie-cli.mjs into .agents/skills/ for terminal-enabled coding agents like Claude Code, Codex CLI, and Gemini CLI—using zero context tokens until invoked. The stdio MCP Server (node kie-cli.mjs mcp) exposes typed JSON-RPC tools for desktop apps like Claude Desktop, Cursor, and Windsurf when shell execution is sandboxed.

How does the --max-credits per-task price check work?

+

Before calling createTask, --max-credits <N> (or KIE_MAX_CREDITS) queries live KIE catalog prices, narrows matching tiers using your input parameters (such as resolution, mode, duration, and image count), and checks the conservative upper bound (Math.max). If the catalog upper bound exceeds N—or if no catalog price can be verified—kie-cli.mjs exits locally with code 3 before sending the task. For account-wide key limits, configure Safe Spend on the API Keys page.

How does the MCP server avoid 60-second desktop tool timeouts on video generation?

+

kie_submit_task caps inline polling at 20 seconds. Fast image tasks return their finished output URLs directly, while longer video or music jobs return { taskId, state: "generating" } before any desktop host timeout fires, instructing the agent to poll kie_task_status(taskId) rather than resubmitting a duplicate paid task.

Where can LLMs read KIE documentation in plain Markdown?

+

Point any LLM or agent at https://kie.ai/llms.txt for the top-level CLI, Skills, and MCP index, or fetch https://kie.ai/model/{slug}.md (for example, https://kie.ai/model/kling-4-0/image.md) for any individual model’s Markdown specification. Every model page header also includes a single-click "Use with Agent / CLI" button with Copy .md and View .md shortcuts.