kie-ai-tool: MCP server, CLI, skills and agent for kie.ai
An open-source toolkit that lets AI agents (Claude Code, Codex, Cursor, Claude Desktop, WorkBuddy or
any MCP client) make images, video, music and speech with kie.ai, safely and
cheaply.
kie.ai resells 200+ generation models (GPT Image 2, Nano Banana, Seedream, Veo 3.1,
Kling 3.0, Seedance, Gemini Omni, Suno, ElevenLabs and more) behind one API key, usually well below
the official price. This repo gives agents a proper way to use it: find the right model, show the
price, wait for your yes, generate, and hand back the files.
Status: early, under active development. Works today: the MCP server and CLI, with every
model in kie.ai's live catalog (search, schemas, prices, health, balance) behind a
prepare → approve → submit step. The plugin install, the creative skills and the agent are being
built now. See the roadmap.
What an agent can do with it
| Tool | Cost | What it does |
|---|
search_models | free | Search kie.ai's live catalog of 200+ models by words, task type or provider |
get_model_schema | free | A model's input fields, required ones, allowed values, defaults and an example |
get_model_status | free | kie.ai's price text and the model's success rate over the last hour and day |
get_balance | free | Credits left on your key |
prepare_media_generation | free | Checks a request against the model's live schema, prices it, saves a plan |
approve_media_generation | free | Chat approval mode: records your yes to a plan |
submit_media_generation | spends | Runs an approved plan once |
run_model | spends | Any catalog model, inside a plan |
gpt_image_2, kling_video, … | spend | 28 hand-tuned model tools with safe defaults, inside a plan |
wait_for_task, get_task_status | free | Waits for a task and returns every result URL |
What's inside
| Part | Path | What it does |
|---|
| MCP server | packages/mcp | Exposes kie.ai models as MCP tools, over stdio or Streamable HTTP |
| CLI | packages/cli | The same tools from the terminal (kie <tool> --flags) |
| OpenAI-compatible server | packages/openai | Selected image and video models behind OpenAI-shaped routes |
| Shared core | packages/core | kie.ai client, tool registry, pricing, plans, task store |
| Skills | skills/ | What agents load to use the toolkit well (below) |
| Agent | agents/kie-director.md | A ready-made agent that plans, prices, gets your approval, produces and checks media |
| Plugin bundles | bundle/ | The MCP server and CLI as single files with no dependencies, so a plain clone runs |
Skills
| Skill | For |
|---|
generate-media | The core workflow: find a model, plan, get approval, generate, check; kie.ai field notes |
image-prompts | Prompts for GPT Image 2, Nano Banana and Seedream: edits, text in images, reference sheets, storyboard frames |
video-prompts | Motion prompts for Veo 3.1, Seedance, Gemini Omni and Kling, lip-sync, dialogue fit, diagnosing bad clips |
product-photoshoot | E-commerce and ad images from real product photos, keeping the product faithful |
youtube-thumbnail | Truthful, high-contrast 16:9 thumbnails with the creator's face and a text overlay |
short-video | A finished vertical reel or explainer: script, look and sequence reviews as images, clips, voice, ffmpeg assembly |
The kie-director agent uses them to take a brief to finished files.
Install
You need Node.js 22.13 or newer, git, and a kie.ai API key from
kie.ai/api-key. Nothing else: the server is one file with no dependencies.
Claude Code (plugin: MCP server, skills and agent in one step)
In Claude Code:
/plugin marketplace add tansilandre/kie-ai-tool-mcp-skills-agent
/plugin install kie@kie-ai-tool
Claude Code asks for your kie.ai API key and keeps it in your system's secure storage, and lets
you pick the approval mode and the credit caps. Change them later with
/plugin configure kie@kie-ai-tool. Then ask in plain words, for example "make a 1:1 product
photo of a white ceramic mug with GPT Image 2 at 1K and save it to ./out". The skills (such as
kie:generate-media, kie:image-prompts, kie:short-video) and the kie-director agent load on
their own; the tools appear as mcp__plugin_kie_kie__*.
Everything else: the installer
macOS and Linux:
curl -fsSL https://raw.githubusercontent.com/tansilandre/kie-ai-tool-mcp-skills-agent/main/install.sh | sh
Windows (PowerShell):
irm https://raw.githubusercontent.com/tansilandre/kie-ai-tool-mcp-skills-agent/main/install.ps1 | iex
It clones the toolkit into ~/.kie-ai-tool (run it again to update), checks Node.js, and prints
the exact setup for the AI apps it finds. Run the downloaded script with --register
(-Register on Windows) to also install the Claude Code plugin and add the skills to Codex. It
never asks for your key. The Windows installer has not been tested on Windows yet: please report
problems in an issue.
Or set it up by hand:
-
Codex: codex mcp add kie --env KIE_API_KEY=<your key> --env KIE_AI_APPROVAL=chat -- node ~/.kie-ai-tool/bundle/kie-mcp.mjs,
and copy the folders in ~/.kie-ai-tool/skills to ~/.codex/skills. (Codex can also install
this repo as a plugin with codex plugin marketplace add tansilandre/kie-ai-tool-mcp-skills-agent
and codex plugin add kie@kie-ai-tool; then set KIE_API_KEY in the environment Codex starts
from. The install is verified; a live Codex session with the plugin is not yet.)
-
Claude Desktop, Cursor, WorkBuddy and other MCP apps: add the server to the app's MCP
settings with the absolute path to your clone:
{
"mcpServers": {
"kie": {
"command": "node",
"args": ["/absolute/path/to/.kie-ai-tool/bundle/kie-mcp.mjs"],
"env": { "KIE_API_KEY": "your-key", "KIE_AI_APPROVAL": "chat" }
}
}
}
On Windows the path looks like "C:\\Users\\you\\.kie-ai-tool\\bundle\\kie-mcp.mjs" (backslashes doubled
in JSON). Use "form" instead of "chat" if the app shows MCP approval forms; without them, form
mode can prepare plans but never approve them.
-
Skills in other agents: the folders in skills/ follow the common SKILL.md layout; copy them
into your agent's skills folder (for example ~/.agents/skills).
CLI
export KIE_API_KEY=your-key # Windows PowerShell: $env:KIE_API_KEY = "your-key"
node ~/.kie-ai-tool/bundle/kie-cli.mjs --help
node ~/.kie-ai-tool/bundle/kie-cli.mjs search_models --query veo
node ~/.kie-ai-tool/bundle/kie-cli.mjs get_model_schema --model gpt-image-2-text-to-image
node ~/.kie-ai-tool/bundle/kie-cli.mjs get_balance
How spending works
Credits are real money (1 credit is about US$0.005), so every paid generation goes through a plan:
-
Prepare. prepare_media_generation checks the request (against the model's live schema for
run_model), fills in cheap defaults you didn't set, and prices it: an exact quote where one
is known, otherwise an upper-bound estimate from kie.ai's own price list. Nothing is sent to
kie.ai yet.
-
Approve. Who says yes depends on KIE_AI_APPROVAL, which only the person who starts the
server or CLI can set:
| Mode | Who approves | Use it for |
|---|
form (default) | You, in the app's approval dialog. In the CLI you type a code it shows you in your terminal | Claude Code, apps that show MCP forms, the CLI used by a person |
chat | You, in chat: the agent shows the plan, you say yes, it calls approve_media_generation | Cursor, Codex, WorkBuddy and other apps without approval forms |
auto | Nobody, for plans up to KIE_AI_AUTO_APPROVE_CREDITS | Unattended pipelines |
-
Submit. submit_media_generation runs an approved plan once and returns every task it
created, even when one item fails, so nothing gets paid for twice.
Caps hold in every mode, enforced in code: no plan above KIE_AI_MAX_CREDITS_PER_PLAN
(default 150 credits), and no more than KIE_AI_MAX_CREDITS_PER_DAY (default 600) in any 24 hours,
counting what kie.ai actually charged where it reports it. A plan with an unknown price needs a
person to accept that explicitly, and auto mode never approves one.
What these controls can and can't do:
- They stop accidents and keep an honest agent inside your limits. They don't stop a determined
agent: in
chat mode it relays your answer, and an agent with a shell can change the CLI's
environment or call kie.ai with your key directly. For agents, the hard limit is a kie.ai API key
with its own credit limit.
- An item with an unknown price counts as a full plan (
KIE_AI_MAX_CREDITS_PER_PLAN) until kie.ai
reports its real charge, which can be higher. Estimates are upper bounds; when kie.ai prices a
model by characters, tokens, megapixels or input media, the estimate is "unknown" instead.
- An item that returns no task id (rejected, or timed out) keeps its estimate booked for 24 hours,
since a timeout can hide a task kie.ai did create.
- The ledger lives in the local task database, so separate machines or databases don't share it.
- The OpenAI-compatible server in
packages/openai is outside these controls.
KIE_AI_ALLOW_DIRECT_GENERATION=true turns plans off entirely; leave it off.
Configuration
| Variable | Required | Purpose |
|---|
KIE_AI_API_KEY | yes | Your kie.ai API key. KIE_API_KEY, the name kie.ai's own docs use, works too |
KIE_AI_CACHE_DIR | no | Where model schemas are cached (default ~/.kie-ai/cache, kept 24 hours) |
KIE_AI_ENABLED_TOOLS | no | Comma-separated tool names to load, to keep the agent's context small |
KIE_AI_TOOL_CATEGORIES | no | Load whole categories: image, video, audio, catalog (run_model), utility |
KIE_AI_DISABLED_TOOLS | no | Tools to hide. Disabling a model tool such as veo3_generate_video does not stop the same model through run_model; disable run_model too |
KIE_AI_APPROVAL | no | form (default), chat or auto. See "How spending works" |
KIE_AI_MAX_CREDITS_PER_PLAN | no | Cap per plan, default 150 credits |
KIE_AI_MAX_CREDITS_PER_DAY | no | Cap per 24 hours, default 600 credits |
KIE_AI_AUTO_APPROVE_CREDITS | no | Auto mode: largest plan approved without asking, default 0 |
KIE_AI_ALLOW_DIRECT_GENERATION | no | true lets every paid tool, including run_model with any catalog model, run without a plan. Leave it off |
KIE_AI_DB_PATH | no | Where tasks and plans are stored (default ~/.kie-ai/tasks.db) |
KIE_AI_CALLBACK_URL | no | Your own webhook for task completion |
The full reference for every tool, transport and option is in docs/TOOLS.md,
docs/DEPLOY_HTTP.md and the archived upstream README.
Develop
npm ci
npm run build && npm run typecheck && npm test && npm run check
See CONTRIBUTING.md and AGENTS.md. Changes land through pull
requests with green CI.
Credits
This project stands on other people's work:
See NOTICE.md for details.
License
MIT. See LICENSE.
