Skip to content
Back to search

kie-cli-mcp

Kie.ai CLI + MCP Server: Cost efficient media API ready to be used by MCP clients like Claude, Codex, OpenCode or Pi. Generative Ai Models available: Nano Banana Pro, Veo3 , Runway Aleph, Suno V5.5, ElevenLabs, Seedance 2.5, Seedream, Qwen, Flux, Wan, Midjourney and OpenAI Image 2

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/felores--kie-cli-mcp/badge.svg)](/listings/felores--kie-cli-mcp)

HTML

<a href="/listings/felores--kie-cli-mcp"><img src="/api/listings/felores--kie-cli-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Requires Node.js >= 20** to run the MCP server.

Add Kie.ai to your MCP client. Pick how many tools you want loaded:

Load all tools (simplest)

{
  "mcpServers": {
    "kie-ai": {
      "command": "npx",
      "args": ["-y", "@felores/kie-ai-mcp-server"],
      "env": {
        "KIE_AI_API_KEY": "your-api-key-here"
      }
    }
  }
}

This makes **every** tool available, so every tool's schema goes into your context.

Load only the tools you need (save tokens, recommended)

Add `KIE_AI_ENABLED_TOOLS` with a comma-separated list; only those tools load:

{
  "mcpServers": {
    "kie-ai": {
      "command": "npx",
      "args": ["-y", "@felores/kie-ai-mcp-server"],
      "env": {
        "KIE_AI_API_KEY": "your-api-key-here",
        "KIE_AI_ENABLED_TOOLS": "nano_banana_image,veo3_generate_video,suno_generate_music"
      }
    }
  }
}

This loads **only** those tools (plus the always-on utility tools), keeping your context lean.

**Get your free API key:** [kie.ai/api-key](https://kie.ai/api-key). No callback URL setup required, the server handles it automatically.

**For Claude Desktop:** add this to `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). Also works with Cursor, Windsurf, VS Code, Claude Code, OpenCode, Droid, and others.

πŸŽ›οΈ More ways to filter

Same idea, different env vars (inside the `env` block, or as shell exports for the CLI, e.g. `export KIE_AI_ENABLED_TOOLS="nano_banana_image,veo3_generate_video"`):

// Load whole categories instead of naming each tool
"KIE_AI_TOOL_CATEGORIES": "image,video"

// Or load everything EXCEPT some tools
"KIE_AI_DISABLED_TOOLS": "midjourney_generate,runway_aleph_video"

- **Categories:** `image`, `video`, `audio`, `utility`. - **Priority:** `ENABLED_TOOLS` > `TOOL_CATEGORIES` > `DISABLED_TOOLS` > all tools (default). - Utility tools, including task tracking and upload helpers, are always enabled and cannot be disabled. - Official MCP Tasks are experimental and opt-in: set `KIE_AI_MCP_TASKS=true` to declare the `tasks` capability, per-tool `execution.taskSupport`, and the task-mode `tools/call` surface. The published MCP SDK still negotiates at most 2025-11-25, so task-mode calls are currently refused with a clear error instead of running; the surface activates once the SDK negotiates the 2026-07-28 revision. Legacy `get_task_status` / `list_tasks` / `wait_for_task` remain available in all modes. - MCP hides and rejects direct `image`, `video`, and `audio` tool calls by default. Use `prepare_media_generation`, host approval elicitation, and `submit_media_generation` instead. `KIE_AI_ALLOW_DIRECT_GENERATION=true` is the explicit legacy bypass when you intentionally disable these approval safeguards. Filtering still controls which generation tools can be plan targets. - MCP hides and rejects direct `image`, `video`, and `audio` tool calls by default. Use `prepare_media_generation`, host approval elicitation, and `submit_media_generation` instead. `KIE_AI_ALLOW_DIRECT_GENERATION=true` is the explicit legacy bypass when you intentionally disable these approval safeguards. Filtering still controls which generation tools can be plan targets. Use `prepare_media_generation`, host approval elicitation, and `submit_media_generation` instead. `KIE_AI_ALLOW_DIRECT_GENERATION=true` is the explicit legacy bypass when you intentionally disable these approval safeguards. Filtering still controls which generation tools can be plan targets.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 527 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <pre>
  3. β–ˆβ–ˆβ•— β–ˆβ–ˆβ•—β–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—
  4. β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•”β•β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•”β•β•β•β•β•
  5. β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β• β–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—
  6. β–ˆβ–ˆβ•”β•β–ˆβ–ˆβ•— β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•”β•β•β•
  7. β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•—β–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—
  8. β•šβ•β• β•šβ•β•β•šβ•β•β•šβ•β•β•β•β•β•β•
  9. C L I / M C P
  10. </pre>
  11. </div>
  12. <p align="center">πŸ‡¬πŸ‡§ <b>English</b> &nbsp;Β·&nbsp; πŸ‡ͺπŸ‡Έ <a href="README.es.md">EspaΓ±ol</a></p>
  13. # Kie.ai CLI + MCP Server + Agent Skill
  14. **One API for state-of-the-art AI media models (Veo 3, Nano Banana, Suno, Kling, Flux, ElevenLabs, Seedance and more), exposed as both an MCP server and a standalone CLI generated from one shared tool registry.** Generate video, images, music and speech from Claude, Codex, OpenCode, Pi-mono, or any agentic harness, or straight from your terminal.
  15. > ## ⚑ Token-efficient by design
  16. >
  17. > An MCP server injects **every** tool's schema into your model's context on **every turn**: with a catalog this large, that's a lot of tokens spent on tools you may never call.
  18. >
  19. > This server fixes that: load **only the tools you actually use** with `KIE_AI_ENABLED_TOOLS` (or whole categories with `KIE_AI_TOOL_CATEGORIES`). Your context stays lean and you pay for exactly the surface you need, no more, no less.
  20. >
  21. ## Two ways to use it (one shared core)
  22. The MCP server and the CLI are generated from the same tool registry, so both expose the exact same models and install **independently**:
  23. - **MCP server**: `@felores/kie-ai-mcp-server`, for Claude Desktop and other MCP clients. See **Quick Start** below.
  24. - **CLI**: `@felores/kie-cli` (binary `kie-cli`), for the terminal, no MCP client needed: `npm i -g @felores/kie-cli`, then `kie-cli --help`. See [`packages/cli/README.md`](packages/cli/README.md).
  25. - **OpenAI transport**: `@felores/kie-ai-openai-server`, a loopback HTTP server for selected image/video models. Version 0.8 upgrades GPT Image to 2.5 Flare, Qwen to Qwen3, and HappyHorse to 1.1 while preserving compatibility IDs. See [`docs/openai-transport.md`](docs/openai-transport.md).
  26. The MCP server runs locally over **stdio** by default, and can also run as a **remote HTTP service** (Streamable HTTP) so one shared instance serves many clients over the network. It ships with a **Dockerfile and a Coolify compose file** for one-step self-hosting ([deploy guide](docs/DEPLOY_HTTP.md)). See the **Remote / HTTP transport** section below.
  27. ## Secure reference uploads
  28. - `upload_file` sends validated Base64 directly to Kie. The CLI can also read a
  29. local path only beneath explicit `KIE_CLI_UPLOAD_ROOTS`. Arbitrary URL import
  30. is intentionally unavailable.
  31. - `upload_widget` renders a minimal MCP Apps file picker when the host supports
  32. `ui://` resources.
  33. - Remote operators may enable temporary capability storage with
  34. `KIE_MCP_PUBLIC_BASE_URL`. Upload minting stays behind authenticated MCP;
  35. one-use upload URLs stay in app metadata. Only an opaque `media_id` reaches
  36. model content; the server resolves it to Kie immediately before submission.
  37. See [the HTTP deployment guide](docs/DEPLOY_HTTP.md).
  38. ## Safe media workflow
  39. Version 4 makes cost control a server-side workflow instead of an agent instruction:
  40. | Surface | Prepare | Human approval | Submit |
  41. | --- | --- | --- | --- |
  42. | MCP | `prepare_media_generation` | Host `elicitation.form` confirmation, or `approve` = plan ID after a chat yes when the client has no elicitation | `submit_media_generation` |
  43. | CLI | `prepare_media_generation` | `--approve <plan-id>` | `submit_media_generation` |
  44. Preparation validates one to six requests, resolves model settings and policy defaults, records pricing as `exact` only for verified formulas and `unknown` otherwise, and creates no provider task. A plan is persistent, expires after 15 minutes by default, is bound to its MCP server session, and can be submitted only once. See [Media planning and approval](#media-planning-and-approval) for the complete flow.
  45. ## πŸš€ Quick Start
  46. **Requires Node.js >= 20** to run the MCP server.
  47. Add Kie.ai to your MCP client. Pick how many tools you want loaded:
  48. ### Load all tools (simplest)
  49. ```json
  50. {
  51. "mcpServers": {
  52. "kie-ai": {
  53. "command": "npx",
  54. "args": ["-y", "@felores/kie-ai-mcp-server"],
  55. "env": {
  56. "KIE_AI_API_KEY": "your-api-key-here"
  57. }
  58. }
  59. }
  60. }
  61. ```
  62. This makes **every** tool available, so every tool's schema goes into your context.
  63. ### Load only the tools you need (save tokens, recommended)
  64. Add `KIE_AI_ENABLED_TOOLS` with a comma-separated list; only those tools load:
  65. ```json
  66. {
  67. "mcpServers": {
  68. "kie-ai": {
  69. "command": "npx",
  70. "args": ["-y", "@felores/kie-ai-mcp-server"],
  71. "env": {
  72. "KIE_AI_API_KEY": "your-api-key-here",
  73. "KIE_AI_ENABLED_TOOLS": "nano_banana_image,veo3_generate_video,suno_generate_music"
  74. }
  75. }
  76. }
  77. }
  78. ```
  79. This loads **only** those tools (plus the always-on utility tools), keeping your context lean.
  80. **Get your free API key:** [kie.ai/api-key](https://kie.ai/api-key). No callback URL setup required, the server handles it automatically.
  81. **For Claude Desktop:** add this to `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). Also works with Cursor, Windsurf, VS Code, Claude Code, OpenCode, Droid, and others.
  82. ### πŸŽ›οΈ More ways to filter
  83. Same idea, different env vars (inside the `env` block, or as shell exports for the CLI, e.g. `export KIE_AI_ENABLED_TOOLS="nano_banana_image,veo3_generate_video"`):
  84. ```jsonc
  85. // Load whole categories instead of naming each tool
  86. "KIE_AI_TOOL_CATEGORIES": "image,video"
  87. // Or load everything EXCEPT some tools
  88. "KIE_AI_DISABLED_TOOLS": "midjourney_generate,runway_aleph_video"
  89. ```
  90. - **Categories:** `image`, `video`, `audio`, `utility`.
  91. - **Priority:** `ENABLED_TOOLS` > `TOOL_CATEGORIES` > `DISABLED_TOOLS` > all tools (default).
  92. - Utility tools, including task tracking and upload helpers, are always enabled and cannot be disabled.
  93. - Official MCP Tasks are experimental and opt-in: set `KIE_AI_MCP_TASKS=true` to declare the `tasks` capability, per-tool `execution.taskSupport`, and the task-mode `tools/call` surface. The published MCP SDK still negotiates at most 2025-11-25, so task-mode calls are currently refused with a clear error instead of running; the surface activates once the SDK negotiates the 2026-07-28 revision. Legacy `get_task_status` / `list_tasks` / `wait_for_task` remain available in all modes.
  94. - MCP hides and rejects direct `image`, `video`, and `audio` tool calls by default. Use `prepare_media_generation`, host approval elicitation, and `submit_media_generation` instead. `KIE_AI_ALLOW_DIRECT_GENERATION=true` is the explicit legacy bypass when you intentionally disable these approval safeguards. Filtering still controls which generation tools can be plan targets.
  95. - MCP hides and rejects direct `image`, `video`, and `audio` tool calls by default. Use `prepare_media_generation`, host approval elicitation, and `submit_media_generation` instead. `KIE_AI_ALLOW_DIRECT_GENERATION=true` is the explicit legacy bypass when you intentionally disable these approval safeguards. Filtering still controls which generation tools can be plan targets. Use `prepare_media_generation`, host approval elicitation, and `submit_media_generation` instead. `KIE_AI_ALLOW_DIRECT_GENERATION=true` is the explicit legacy bypass when you intentionally disable these approval safeguards. Filtering still controls which generation tools can be plan targets.
  96. ## πŸ€– Agent skill (optional)
  97. `skills/generate-media/` is the canonical agent workflow. It requires a persisted plan, displays resolved settings and verified pricing state, then waits for explicit approval before task submission. `skills/kie-ai/` is a migration pointer only. Skills load **globally**, so install the canonical skill into your personal skills dir:
  98. ```bash
  99. cp -r skills/generate-media ~/.claude/skills/generate-media
  100. # or symlink to keep it in sync with the repo:
  101. ln -s "$PWD/skills/generate-media" ~/.claude/skills/generate-media
  102. ```
  103. Then any session can prepare media in plain language ("make me an image of...", "turn this photo into a video") and request approval before a paid task starts.
  104. ## Media planning and approval
  105. Use `list_models` to search source-backed capabilities, then prepare one to six requests in a single persisted plan. Preparing validates target schemas and applies safe defaults, but never calls a Kie generation endpoint.
  106. ```json
  107. {
  108. "tool": "prepare_media_generation",
  109. "arguments": {
  110. "items": [
  111. { "tool": "nano_banana_image", "args": { "prompt": "A red panda coding at night" } }
  112. ]
  113. }
  114. }
  115. ```
  116. For MCP clients that advertise and handle the `elicitation.form` capability, preparation shows the complete resolved plan and price summary in a host confirmation form. Only an accepted form with `confirm: true` records the plan as approved. Declined, cancelled, and unconfirmed forms leave the plan unapproved. Clients that do not advertise `elicitation` (for example the Claude desktop Code tab) approve in chat instead: the agent shows the full plan with its credit and USD price, and only after the user clearly says yes for that exact plan, calls `submit_media_generation` with `approve` equal to `planId`. This mirrors the CLI `--approve <plan-id>`, atomically moves the plan from `prepared` to `approved`, and submits it. A missing or mismatched `approve` is rejected, and clients that can show the form cannot use `approve` to skip it. Submit only the resulting approved plan ID:
  117. ```json
  118. {
  119. "tool": "submit_media_generation",
  120. "arguments": {
  121. "planId": "<approved-plan-id>"
  122. }
  123. }
  124. ```
  125. The CLI has no MCP host. It requires an explicit `--approve <plan-id>` value matching `--planId`; this atomically changes a prepared plan to approved before submission.
  126. Pricing refresh is read-only by default: `npm run pricing:refresh` reports the tracked source evidence freshness and does not fetch, scrape, or write. `npm run pricing:refresh -- --apply` is an explicit metadata-only boundary. It is an intentional no-op without eligible validated formula proposals; with `--proposals <file>`, it can record the proposed deterministic credits formula plus its source URL, fingerprint, verification date, scope, and test evidence in the rate-card evidence manifest. It never edits executable formulas or the USD conversion constant.
  127. ```bash
  128. kie-cli submit_media_generation --planId <prepared-plan-id> --approve <prepared-plan-id> --json
  129. ```
  130. Plans are persisted in the local SQLite database and move atomically from `prepared` to `approved`, `submitting`, and then `submitted` or `failed`. They expire after 15 minutes by default, cannot be modified, and cannot be submitted twice. The request hash detects accidental plan mutation only. An MCP plan is also bound to the server instance that prepared and approved it, so another HTTP session cannot submit it. A submitted batch creates no more than four provider tasks concurrently. Exact credit quotes exist only for verified request dimensions; all other requests are `unknown`. Exact quotes also carry a USD conversion at Kie's published credit value of $0.005 per credit (source: kie.ai/pricing), labelled as a conversion; unknown prices carry no USD.
  131. ## Models
  132. A unified, always-current catalog organized by job:
  133. ### Video generation
  134. | Model | Best for | Tool |
  135. | --- | --- | --- |
  136. | **ByteDance Seedance 2.5** | Multimodal references, experimental semantic task continuation, first/last-frame control, and native audio | `bytedance_seedance_video` |
  137. | **Kling 3.0** | Multi-shot videos and native audio | `kling_video` |
  138. | **Google Veo 3 / 3.1** | Cinematic generation with synchronized audio and 1080p output | `veo3_generate_video` |
  139. | **Gemini Omni** | Videos with reusable characters and voices | `gemini_omni` |
  140. | **MiniMax H3 (Hailuo 03)** | Text, first/last-frame, and multimodal reference-to-video | `hailuo_video` |
  141. | **Wan 3.0 / Prime** and **HappyHorse 1.1** | Multimodal references and video generation | `wan_video`, `happyhorse_video` |
  142. ### Video editing and avatars
  143. - **Runway Aleph**: video-to-video transformation and editing
  144. - **Midjourney** and **Grok Imagine**: image-to-video, stylized generation, and Grok Imagine Image 2.0 image editing
  145. - **Wan Animate**: character animation and replacement
  146. - **OmniHuman 1.5**, **Kling Avatar**, and **InfiniTalk**: talking avatars and lip sync
  147. ### Image generation and editing
  148. - **Nano Banana 2 / Lite**, **GPT Image 2.5**, **Seedream 5 Pro / Flash**, **Qwen3 / Pro**, **Wan 2.7 Image / Pro**, **Flux Kontext / Flux 2**, and **Z-Image**: generation and image editing
  149. - **Ideogram**, **Recraft**, and **Topaz**: reframing, background removal, and upscaling
  150. ### Audio
  151. - **Suno V6 / Mini / Wild**: music generation with lyrics, personas, media references, and custom duration control
  152. - **ElevenLabs**: text-to-speech and sound effects
  153. Each tool features **smart mode detection**: one tool handles generate / edit / upscale based on the parameters you pass.
  154. **The complete, current list is always available:** run `kie-cli --help` (and `kie-cli <tool> --help` for a tool's flags), or see **[docs/TOOLS.md](docs/TOOLS.md)**.
  155. ## MCP resources & prompts
  156. Beyond tools, the MCP server exposes (all generated from the registry, so they never drift):
  157. - **Prompts** (slash commands in your client): `/image` and `/video`: guidance for picking and driving the right model.
  158. - **Resources:**
  159. - `kie://tools/<name>`: a Markdown reference for each tool (parameters, types, defaults), generated from its schema.
  160. - `kie://guides/image-models-comparison`, `kie://guides/video-models-comparison`, `kie://guides/quality-optimization`: model comparison and cost/quality guides.
  161. - `kie://tasks/active`, `kie://stats/usage`: live view of the local task database.
  162. - `ui://kie/upload.html`: sandboxed MCP Apps upload widget.
  163. ## What's new in MCP 5.6.2
  164. - Completed task results now carry `result_urls` in structured content, so clients that read structured content receive the output URLs from `wait_for_task`.
  165. ## What's new in MCP 5.6.1
  166. - Fixes `prepare_media_generation` failing on strict MCP clients with "Structured content does not match the tool's output schema". The declared output schema now includes the plan.
  167. ## What's new in MCP 5.6.0
  168. - Prepared plans show each item's price in credits and in USD (Kie's published $0.005 per credit, labelled as a conversion), and the full plan is returned in the prepare result. Unknown prices stay `unknown`.
  169. - Clients without form elicitation approve in chat: `submit_media_generation` accepts `approve` equal to `planId` after the user confirms the shown plan.
  170. ## What's new in MCP 5.5.0
  171. - Exact credit formula for ByteDance Seedance 2.5 without reference video: 28, 63, and 158 credits per second at 480p, 720p, and 1080p, multiplied by the generated duration.
  172. ## What's new in MCP 5.4.0
  173. - Exact credit formulas for Qwen z-image (0.8 per image), Recraft Remove Background (1 per image), and Wan 2.7 Image (4.8 standard and 12 Pro, per image).
  174. ## What's new in MCP 5.3.2
  175. - GPT Image 2.5 now quotes 2K at 10 credits and 4K at 16 credits per image, and image-to-image at the same per-resolution price. 1K stays at 6 credits.
  176. ## What's new in MCP 5.3.1
  177. - GPT Image 2.5 Flare and Sunburst at 1K now quote an exact price: 6 credits per image. 2K, 4K, and image-to-image remain `unknown`.
  178. ## What's new in MCP 5.3.0
  179. - The GPT Image tool is now `gpt_image`. The model is still GPT Image 2.5 (Flare and Sunburst). Update `KIE_AI_ENABLED_TOOLS` and any saved plan that names the old `gpt_image_2`.
  180. ## What's new in MCP 5.2.0
  181. - Suno V6/Mini/Wild, GPT Image 2.5 Flare/Sunburst, Seedream 5 Pro/Flash and layers, Qwen3/Pro, and HappyHorse 1.1 replace retired provider versions.
  182. - `wan_video` adds Wan 3.0 Prime. New `wan_image` supports Wan 2.7 Image/Pro, up to nine references, sequential output, palettes, and bounding-box editing.
  183. - Shared core changes ship in CLI 0.10 and selected OpenAI adapters in transport 0.8. Historical task polling and transport aliases remain; old provider generation routes are removed. Unverified pricing remains `unknown`.
  184. Migration examples:
  185. ```bash
  186. kie-cli suno_generate_music --customMode --instrumental --model V6 --style "Ambient piano" --title "Quiet"
  187. kie-cli gpt_image --model sunburst --prompt "A glass perfume bottle" --background transparent
  188. kie-cli bytedance_seedream_image --version 5-flash --size 1.5K --prompt "A botanical poster"
  189. kie-cli bytedance_seedream_image --version 5-pro --image_url https://example.com/product.png
  190. kie-cli qwen_image --model qwen3-pro --resolution 2K --prompt "A product photo"
  191. kie-cli happyhorse_video --image_urls https://example.com/scene.png --duration 5
  192. kie-cli wan_video --model wan/3-0-video-prime --prompt "A mountain lake at sunrise"
  193. kie-cli wan_image --model wan/2-7-image-pro --resolution 4K --n 1 --prompt "A city map"
  194. ```
  195. Suno prompt-only non-custom requests now fail validation. Qwen editing uses `image_urls`; retired inference controls are rejected. Seedream Flash uses `size`, Pro uses `quality`, and one `image_url` selects layers. See the [current endpoint contracts](docs/ENDPOINTS.md).
  196. ### MCP 5.1
  197. - **Wan 3.0.** `wan_video` now uses the unified `wan/3-0-video` model with
  198. text, first/last frames, up to 10 image references, 5 video references,
  199. 5 audio references, documents, webpages, native audio, and 2-30 second clips.
  200. - **Shared release.** The same Wan 3.0 contract ships in CLI 0.9 and OpenAI
  201. transport 0.7. The OpenAI route accepts `kie-wan-3-0-video` and keeps
  202. `kie-wan-2-7-video` as a compatibility alias.
  203. ### MCP 5.0 foundation
  204. Built on the **SDK v2 packages** (`@modelcontextprotocol/server`,
  205. `@modelcontextprotocol/node`) with **Node >= 20** and **zod v4**:
  206. - **Dual protocol era.** The server negotiates the protocol version per client:
  207. 2025-era clients keep working unchanged, while the 2026-07-28 vocabulary
  208. (`server/discover`, cache hints, extensions, structured schemas, tasks) is
  209. served as soon as the SDK lifts its negotiation cap.
  210. - **Structured results.** Failed tool calls arrive as `isError: true` with
  211. structured error content; generation, upload and planning tools expose
  212. `structuredContent` (`task_id`, `media_id`, `plan_id`) and advertise
  213. `outputSchema` in `tools/list`.
  214. - **Modern input schemas.** Tool `inputSchema` is generated as JSON Schema
  215. 2020-12, the dialect MCP 2026-07-28 targets.
  216. - **MRTR plan approval.** On 2026-era hosts approval is a multi-round-trip
  217. `input_required` flow; 2025-era hosts keep the push-style elicitation.
  218. - **`server/discover` + cache hints + extension negotiation.** The server
  219. answers discovery with its supported versions, capabilities and
  220. instructions, and advertises the MCP Apps extension that gates the upload
  221. widget resource.
  222. - **Official MCP Tasks (opt-in).** `KIE_AI_MCP_TASKS=true` exposes the `tasks`
  223. capability and task-mode `tools/call` runs backed by an in-process engine
  224. mirrored to the local SQLite database; legacy `get_task_status` /
  225. `list_tasks` / `wait_for_task` remain available in all modes.
  226. ## Examples
  227. ### MCP (prepare, approve, submit)
  228. Prepare the paid request first. This does not start generation:
  229. ```json
  230. {
  231. "tool": "prepare_media_generation",
  232. "arguments": {
  233. "items": [
  234. {
  235. "tool": "nano_banana_image",
  236. "args": {
  237. "prompt": "A futuristic city at sunset, cyberpunk style",
  238. "aspect_ratio": "16:9",
  239. "resolution": "2K",
  240. "output_format": "png"
  241. }
  242. }
  243. ]
  244. }
  245. }
  246. ```
  247. The MCP host then presents the returned plan, resolved settings, and price summary with `elicitation.form`. Approve that host form with `confirm: true`; the approved response includes a `planId`. Then submit that approved plan. Without form elicitation, show the user the plan and price, wait for a clear yes in chat, and submit with `"approve": "<plan-id>"` alongside `planId`:
  248. ```json
  249. {
  250. "tool": "submit_media_generation",
  251. "arguments": {
  252. "planId": "<approved-plan-id>"
  253. }
  254. }
  255. ```
  256. Do not call paid media tools directly from MCP. `KIE_AI_ALLOW_DIRECT_GENERATION=true` is only the explicit legacy bypass.
  257. ### CLI
  258. ```bash
  259. # 1. Prepare one or more paid requests. This creates no provider task.
  260. kie-cli prepare_media_generation \
  261. --items '[{"tool":"nano_banana_image","args":{"prompt":"a red panda coding at night, neon","resolution":"2K"}}]' \
  262. --json
  263. # 2. Review the returned plan, then explicitly approve and submit it.
  264. kie-cli submit_media_generation \
  265. --planId <prepared-plan-id> \
  266. --approve <prepared-plan-id> \
  267. --json
  268. # 3. Wait for a returned task ID in one call.
  269. kie-cli wait_for_task --task_id <id> --json
  270. # Other supported jobs use the same prepare -> approve -> submit flow.
  271. # The raw generation commands below remain lower-level compatibility APIs.
  272. kie-cli suno_generate_music --style "Upbeat electronic, energetic" --customMode --instrumental --model V6 --title "Energy Boost"
  273. kie-cli elevenlabs_tts --text "Welcome to the future of content creation!" --voice Rachel --model turbo
  274. ```
  275. Use `prepare_media_generation` for any paid CLI job when you need approval, quotes, defaults, batch control, or replay protection. The raw commands remain available for scripts that deliberately own their own safety boundary. Generation is asynchronous: tools return a `task_id`. Wait for it in a single call with `wait_for_task` (it polls Kie for you and returns the final URLs when ready), or check once with `get_task_status` and browse recent work with `list_tasks`. Add `--json` to the CLI for machine-readable output.
  276. In an MCP client, `wait_for_task` keeps the tool call open and streams `notifications/progress` until the result is ready, so the model gets the URLs without looping. For long jobs (video), enable `resetTimeoutOnProgress` with a generous `maxTotalTimeout` in your client so the call is not cut off at the default timeout.
  277. ## Configuration
  278. <details>
  279. <summary><strong>βš™οΈ Environment variables</strong></summary>
  280. ### Required
  281. ```bash
  282. export KIE_AI_API_KEY="your-api-key-here" # Get from https://kie.ai/api-key
  283. ```
  284. ### Optional
  285. ```bash
  286. export KIE_AI_BASE_URL="https://api.kie.ai/api/v1" # API base URL
  287. export KIE_AI_TIMEOUT="60000" # Request timeout (ms)
  288. export KIE_AI_DB_PATH="./tasks.db" # Task database location
  289. export KIE_AI_CALLBACK_URL="https://your-domain.com/webhook" # Custom callback
  290. export KIE_AI_CALLBACK_URL_FALLBACK="https://your-proxy.com/callback" # Deployment-wide default
  291. ```
  292. ### Callback URL priority
  293. | Priority | Source | Variable |
  294. |----------|--------|----------|
  295. | 1 | Per-request | `callBackUrl` argument |
  296. | 2 | Environment | `KIE_AI_CALLBACK_URL` |
  297. | 3 | Admin fallback | `KIE_AI_CALLBACK_URL_FALLBACK` |
  298. | 4 | Hardcoded default | `https://proxy.kie.ai/mcp-callback` |
  299. See [docs/ADMIN.md](docs/ADMIN.md) for Docker, Kubernetes and Systemd examples.
  300. </details>
  301. <details>
  302. <summary><strong>πŸ“¦ Install from source (for development)</strong></summary>
  303. ```bash
  304. git clone https://github.com/felores/kie-cli-mcp.git
  305. cd kie-cli-mcp
  306. npm install
  307. npm run check # Biome: format + lint + import organization
  308. npm run format # apply Biome formatting
  309. npm run build # build all workspaces
  310. npm run typecheck # type-check all workspaces
  311. npm test # run the test suite
  312. ```
  313. This is an npm-workspaces monorepo: `packages/core` (private shared registry, bundled into the others), `packages/mcp` (`@felores/kie-ai-mcp-server`) and `packages/cli` (`@felores/kie-cli`). To add a model, run `npm run add-tool -- <name> <category>` and both surfaces pick it up. For the dev server with auto-reload: `npm run dev -w @felores/kie-ai-mcp-server`.
  314. </details>
  315. <details>
  316. <summary><strong>🌐 Remote / HTTP transport (v5.0.0+)</strong></summary>
  317. The server defaults to **stdio** (one local process per client). It can also run
  318. as a **remote HTTP service** over **Streamable HTTP**. Since v5.0.0 it is built
  319. on the MCP SDK v2 packages and serves both 2025-era and 2026-07-28 clients by
  320. protocol negotiation.
  321. **Why use it:**
  322. - **One shared instance for many clients** β€” host it once, connect your whole
  323. team or several agents over the network instead of spawning a local process each.
  324. - **Deploy anywhere** β€” runs as a container on any host or PaaS (Dockerfile +
  325. Coolify compose included), behind your own TLS/proxy.
  326. - **Centralized config & task history** β€” a single API key and one shared SQLite
  327. task DB, so generations are tracked in one place.
  328. - **Secured by default off-loopback** β€” bearer-token auth and Host-allowlist
  329. (DNS-rebinding) protection, with an open `/health` endpoint for uptime probes.
  330. - **Zero disruption** β€” stdio stays the default; HTTP is purely opt-in.
  331. Opt in with `MCP_TRANSPORT=http` or `--http`:
  332. ```bash
  333. KIE_AI_API_KEY=sk-... MCP_TRANSPORT=http MCP_HTTP_PORT=3000 \
  334. node packages/mcp/dist/index.js
  335. curl http://127.0.0.1:3000/health
  336. # β†’ {"status":"ok","transport":"streamable-http","sessions":0,"version":"5.6.2"}
  337. ```
  338. Single `/mcp` endpoint (POST + GET/SSE + DELETE), stateful sessions via
  339. `Mcp-Session-Id`, plus an unauthenticated `GET /health`.
  340. | Env | Default | Purpose |
  341. |-----|---------|---------|
  342. | `MCP_TRANSPORT` | `stdio` | set `http` to enable |
  343. | `MCP_HTTP_HOST` | `127.0.0.1` | `0.0.0.0` only in a container / behind a proxy |
  344. | `MCP_HTTP_PORT` | `3000` | listen port |
  345. | `KIE_MCP_HTTP_TOKEN` | _(unset)_ | require `Authorization: Bearer <token>` |
  346. | `MCP_ALLOWED_HOSTS` | _(unset)_ | Host allowlist (DNS-rebind protection); required off-loopback |
  347. Docker + Coolify deployment and a client-connection walkthrough are in
  348. [docs/DEPLOY_HTTP.md](docs/DEPLOY_HTTP.md).
  349. </details>
  350. ## Task management
  351. The server keeps a local SQLite database of prepared plans and tasks, persistent across restarts, used for approval safety, status tracking, and correct endpoint routing.
  352. ```json
  353. { "tool": "list_tasks", "arguments": { "limit": 20, "status": "completed" } }
  354. ```
  355. ```json
  356. { "tool": "get_task_status", "arguments": { "task_id": "281e5b0...f39b9" } }
  357. ```
  358. Note: `list_tasks` reflects the MCP's local cache, tasks it has created or polled, not your full Kie.ai account history. When a provider status response includes `creditsConsumed`, it is returned as actual task usage, separately from a plan quote. See [docs/DATABASE.md](docs/DATABASE.md).
  359. ## Error handling
  360. The server surfaces Kie.ai's response codes (it only treats `code === 200` as success):
  361. | Code | Meaning |
  362. |------|---------|
  363. | 200 | Success |
  364. | 400 | Content policy violation / English prompts only |
  365. | 401 | Unauthorized (invalid API key) |
  366. | 402 | Insufficient credits |
  367. | 404 | Resource not found |
  368. | 422 | Validation error / record is null |
  369. | 429 | Rate limited |
  370. | 455 | Service maintenance |
  371. | 500 | Server error / timeout |
  372. | 501 | Generation failed |
  373. ## Troubleshooting
  374. - **"Unauthorized"**: verify `KIE_AI_API_KEY` is set and valid at [kie.ai/api-key](https://kie.ai/api-key).
  375. - **"Task not found"**: tasks may expire after ~14 days; check the task id.
  376. - **Generation failures**: check content-policy compliance, English prompts, and sufficient credits.
  377. ## Documentation
  378. - [docs/TOOLS.md](docs/TOOLS.md): complete tool reference
  379. - [docs/DATABASE.md](docs/DATABASE.md): database and task lifecycle
  380. - [docs/ADMIN.md](docs/ADMIN.md): deployment and environment setup
  381. - [docs/INTELLIGENCE.md](docs/INTELLIGENCE.md): smart mode detection and cost optimization
  382. ## Support
  383. - **This server (MCP or CLI):** open a pull request at https://github.com/felores/kie-cli-mcp
  384. - **Kie.ai API:** support@kie.ai or https://docs.kie.ai/
  385. - **API keys:** https://kie.ai/api-key
  386. ## Contributing
  387. Fork β†’ feature branch β†’ make your change (add tests if applicable) β†’ open a PR.
  388. ## License
  389. MIT, see [LICENSE](LICENSE).
  390. ## Changelog
  391. See [CHANGELOG.md](CHANGELOG.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.