kie-mcp

A small MCP server that gives your agent access to Kie.ai image and video generation. It discovers models, uploads local reference media, waits for Kie, downloads the result, and returns local paths with Markdown previews.

You need a Kie.ai API key and Rust 1.85 or newer.

rustup update stable
cargo install --git https://github.com/Pym/kie-mcp
command -v kie-mcp

Use the absolute path printed by command -v in your MCP client configuration. The server uses stdio and starts with kie-mcp serve (or simply kie-mcp).

At minimum, pass KIE_API_KEY to the server process. Setting an absolute output directory is recommended because desktop clients do not always start servers from the directory you expect.

[mcp_servers.kie]
command = "/absolute/path/to/kie-mcp"
args = ["serve"]
env_vars = ["KIE_API_KEY", "KIE_MCP_OUTPUT_DIR"]
tool_timeout_sec = 1800

Set KIE_API_KEY and, optionally, KIE_MCP_OUTPUT_DIR in the environment that launches Codex.

{
  "mcpServers": {
    "kie": {
      "command": "/absolute/path/to/kie-mcp",
      "args": ["serve"],
      "env": {
        "KIE_API_KEY": "<your-private-key>",
        "KIE_MCP_OUTPUT_DIR": "/absolute/path/to/kie-output"
      }
    }
  }
}

Configuration filenames and environment forwarding differ between clients, but the contract is always the same: an executable, serve, environment variables, and stdio transport.

Once connected, ask your agent normally:

• "Generate a 16:9 editorial photo with Kie and save it as cover."
• "Turn /absolute/path/product.png into a five-second product video."
• "Show me the available Nano Banana models."
• "How many Kie credits do I have left?"

The server exposes six tools:

Generation tools accept a model, a model-aware optional prompt, and convenience fields such as aspect_ratio, resolution, and output_format. kie_models reports whether each model requires, optionally accepts, or does not use a prompt. A legacy prompt supplied to a promptless model is not forwarded to Kie. Model-specific Kie fields go in input.

For reference media, pass public URLs through input_urls or local image/video files through local_input_paths. Local files are uploaded automatically. These shortcuts require a cataloged media binding; for an uncataloged raw model ID, put every model-specific field directly in input so the server does not guess Kie's field names.

Results are downloaded to output/kie by default. Each task gets its own directory, and successful calls return absolute paths that the agent can reuse.

Advanced endpoints, HTTP timeouts, debug commands, architecture, and known limitations are documented in docs/DEVELOPMENT.md.

• Generations and parallel variants can consume Kie credits.
• Prompts, model inputs, URLs, and uploaded files are sent to Kie.
• Generated files remain on disk until you remove them.
• Keep API keys, signed URLs, and sensitive output directories private.

Tests use a local mock API and do not consume Kie credits. The concurrency regression test launches three simultaneous mocked generations with the same output_name and verifies distinct task IDs, downloads, paths, and contents.

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test

See docs/DEVELOPMENT.md for maintainer notes.

MIT