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

Related MCP server: PixelDojo MCP

What's inside

Skills

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

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.