Kie Ai Tool Mcp Skills Agent

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:

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

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

3. 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:

• andrewlwn77/kie-ai-mcp-server, the original kie.ai MCP server (MIT).
• felores/kie-cli-mcp, which grew it into the CLI, MCP server and OpenAI-compatible server this repo starts from (MIT). The full git history is kept.
• higgsfield-ai/skills (MIT), whose skill design and prompt craft the planned creative skills adapt for kie.ai.
• kie.ai's own docs and agent skills, for the live catalog API.

See NOTICE.md for details.

License

MIT. See LICENSE.