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. Dedicated tools also cover the preparation steps used by Grok Image 2, Gemini Omni Video, and OmniHuman 1.5.
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-mcpUse 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 = 1800Set 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.pnginto a five-second product video." - "Show me the available Nano Banana models."
- "Show me the editable segments in this Grok image."
- "Create a reusable Gemini Omni character from this portrait."
- "How many Kie credits do I have left?"
The server exposes 11 tools. Six cover generation and account operations, while five handle model-specific preparation:
| Tool | Purpose |
|---|---|
kie_generate_image |
Generate or edit an image and download it locally. |
kie_generate_video |
Generate a video and download it locally. |
kie_models |
Find live model IDs, aliases, nested inputs, and constraints. |
kie_gemini_omni_create_audio_profile |
Create an audio profile ID for Gemini Omni Video. |
kie_gemini_omni_create_character |
Create a character ID for Gemini Omni Video. |
kie_grok_image_2_segment_map |
Find Grok Image 2 segments and download their masks. |
kie_omnihuman_human_identification |
Run OmniHuman's portrait identification preflight. |
kie_omnihuman_subject_detection |
Find OmniHuman subjects and download their masks. |
kie_task_status |
Check or download an existing task. |
kie_upload_media |
Upload a local file for model-specific workflows. |
kie_credits |
Read the current account credit balance. |
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.
kie_models reads Kie's current llms.txt index and the OpenAPI document for
each matching image or video route. Every live model entry includes an
input_schema with recursive properties, required fields, enums, defaults,
types, and documented limits. Set include_descriptions to true when field
descriptions are also useful. By default, the response omits descriptions and
examples to keep broad catalog searches compact.
Before uploading local files or creating a task, the generation tools validate
the assembled input against unambiguous constraints in an authoritative live
route schema. This catches invalid enum values, missing required fields, wrong
types, and length, numeric, object, or array bounds locally. Kie still performs
the final validation because some cross-field and media rules exist only in
prose or cannot be checked without reading the remote media. If the public docs
are unavailable or a route lacks a usable OpenAPI contract, the server keeps the
embedded compatibility entry and skips schema-backed validation for that model.
The same safeguard applies when Kie's own documented request example fails
against the schema on that route: kie_models reports
schema_status: informational plus a schema_warning, preserves the schema for
inspecti
79FF
on, and leaves final validation to Kie instead of rejecting the
documented request locally.
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.
The five preparation tools are composable. The server does not call them silently.
- Gemini Omni Audio returns an
audio_id. Pass it to Gemini Omni Character or togemini-omni-videoorgoogle/gemini-omni-flash-1-1throughinput.audio_ids. - Gemini Omni Character returns a
character_id. Pass it togemini-omni-videoorgoogle/gemini-omni-flash-1-1throughinput.character_ids. - Grok Segment Map returns a source
task_idand numbered masks. Generate the targeted edit withkie_generate_imageandmodel: grok-imagine-image-2-0/segment-edit. Supply the edit prompt, put the returned ID ininput.task_id, and place selected indexes of1or greater ininput.mask_indexs. Kie's current Segment Edit schema rejects index0even though Segment Map can return it. The field spelling follows Kie's API. The separategrok-imagine-image-2-0/image-editroute edits up to fiveimage_urlsand does not consume Segment Map task IDs. - OmniHuman Subject Detection returns mask URLs and local previews. Pass the
chosen URLs to
omnihuman-1-5throughinput.mask_url. - OmniHuman Human Identification returns Kie's integer
subject_statusas-is. Kie's documentation does not define the values, so the server does not label them as success or failure.
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.
| Variable | Default | Purpose |
|---|---|---|
KIE_API_KEY |
unset | Required Kie API key. |
KIE_MCP_OUTPUT_DIR |
output/kie |
Directory for downloaded results. |
KIE_MCP_TIMEOUT_SECS |
900 |
Maximum generation wait time. |
KIE_MCP_MAX_UPLOAD_BYTES |
536870912 |
Maximum local upload size. |
KIE_MCP_INPUT_ROOTS |
unset | Optional allowlist of local upload directories. |
KIE_MCP_CATALOG_URL |
https://docs.kie.ai/llms.txt |
Model catalog index, mainly useful for local fixtures and mirrors. |
Advanced endpoints, HTTP timeouts, debug commands, architecture, and known limitations are documented in docs/DEVELOPMENT.md.
- Generation and preparation calls can consume Kie credits.
- Catalog discovery uses unauthenticated requests to
docs.kie.aiand does not 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 testSee docs/DEVELOPMENT.md for maintainer notes.
MIT