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: hedra-mcp-server

What's inside

Install

You need Node.js 22.13 or newer 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. You can change it later with /plugin configure kie@kie-ai-tool. If you leave it empty, the plugin uses KIE_API_KEY from the shell that started Claude Code.

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 kie:generate-media skill and the kie-director agent load on their own; the tools appear as mcp__plugin_kie_kie__*.

From a terminal, the same install is:

claude plugin marketplace add tansilandre/kie-ai-tool-mcp-skills-agent
claude plugin install kie@kie-ai-tool

Any other MCP client (Claude Desktop, Cursor, Codex, WorkBuddy, …)

git clone https://github.com/tansilandre/kie-ai-tool-mcp-skills-agent

Then point the client at the bundled server, using the absolute path to your clone:

{
  "mcpServers": {
    "kie": {
      "command": "node",
      "args": ["/absolute/path/to/kie-ai-tool-mcp-skills-agent/bundle/kie-mcp.mjs"],
      "env": { "KIE_API_KEY": "your-key" }
    }
  }
}

For Codex: codex mcp add kie --env KIE_API_KEY=your-key -- node /absolute/path/to/kie-ai-tool-mcp-skills-agent/bundle/kie-mcp.mjs.

CLI

export KIE_API_KEY=your-key
node bundle/kie-cli.mjs --help
node bundle/kie-cli.mjs search_models --query veo
node bundle/kie-cli.mjs get_model_schema --model gpt-image-2-text-to-image
node bundle/kie-cli.mjs get_balance

How spending works

Every paid generation goes through three steps, so an agent cannot spend your credits without you seeing the plan first:

1. prepare_media_generation checks the request, fills in cheap defaults you didn't set, shows the price when it is known, and saves a plan. Nothing is sent to kie.ai yet.

2. You approve the plan. In an MCP client that supports forms, the server asks you in a form. In the CLI you pass --approve <planId>.

3. submit_media_generation runs the approved plan once.

The MCP server hides the direct generation tools unless its operator sets KIE_AI_ALLOW_DIRECT_GENERATION=true. The roadmap adds credit caps enforced in code and an approval path for MCP clients that don't support forms.

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.