Secure KIE MCP

A local stdio MCP server for creating and editing media with your own KIE account. Choose a model, inspect its parameters and price, approve one immutable request, then wait and save the result. Paid submissions are never retried automatically.

Project repository: Mr-Fulani/mcp-kie. Installation guide · Шпаргалка команд · Security boundary · Contributing. MIT license; inherited attribution is preserved in NOTICE.md.

What is supported

Native Windows, public HTTP MCP, video timeline editing, format conversion and a multi-user SaaS backend are not implemented. WSL2 uses the Linux path; it has not had a separate live acceptance run. Historical tests are evidence for their tested models/settings, not a guarantee that every KIE model works today.

Related MCP server: kie-image-mcp

Install and configure

Install uv, then clone:

git clone https://github.com/Mr-Fulani/mcp-kie.git
cd mcp-kie

Use the committed lockfile:

uv sync --frozen

You need one separate KIE media API key. A KIE chat key, OpenAI key or Anthropic key is not required by this server. Your MCP client has its own independent login. Never paste the media key into chat, terminal command arguments or client JSON/TOML.

1. Create dedicated directories outside the checkout for uploads, results and the ledger, plus ~/.config/kie-mcp (private directory, mode 0700).

2. Review examples/owner-config.toml on macOS or examples/owner-config-linux.toml on Linux/WSL2. Save your edited copy as ~/.config/kie-mcp/config.toml, mode 0600. Use absolute paths or ~, and choose your spending limits before the first paid request. Do not overwrite an existing owner's configuration.

3. On macOS, create a generic-password item in Keychain Access UI: service/name kie-mcp-media, account media, password = your separate media key. On Linux/WSL2, the example uses secret_file: save only your key in ~/.config/kie-mcp/media.key, owned by you with mode 0600/0400, outside uploads, results and Git. Enter it through an editor; it is plaintext on disk, not a vault. Protect its directory and disk. Docker Secret is another supported source at the fixed /run/secrets/KIE_MCP_API_KEY mount; no ready-made container deployment is included. env is an explicit development fallback. .env is not auto-loaded.

4. Run the offline checker:

.venv/bin/kie-mcp-doctor
.venv/bin/kie-mcp-doctor --check-secret

The checker never uses the network or writes files/config/ledger. Default mode never reads the key; --check-secret tests secret loading without displaying it (Keychain may ask for access). PASS does not validate the key with KIE or confirm provider-side caps. Follow with a read-only kie_get_credits call from your client.

Full walkthrough, first task and troubleshooting: Руководство установки и применения.

Connect an MCP client

The registrar previews changes first, backs up before applying, preserves other settings and refuses to overwrite a differing registration. Replace the example with your absolute launcher path; no key goes into client configuration.

.venv/bin/kie-mcp-register codex --command /absolute/checkout/.venv/bin/kie-mcp-launch
# Review the preview, then:
.venv/bin/kie-mcp-register codex --command /absolute/checkout/.venv/bin/kie-mcp-launch --apply

Replace codex with claude or grok. Registration uses ~/.codex/config.toml, ~/.claude.json or ~/.grok/config.toml respectively. Restart the client and inspect its tool list: 23 tools, including kie_compare_models. For another stdio client, configure the launcher as its command with empty args; keep secrets in the launcher source, not the client config. A launcher started alone waits for MCP messages.

To remove only this registration, use the same client/command with --remove --apply. See the client instructions template and official Codex MCP documentation.

Use it

Ask: “Compare suitable KIE models for a product photo. Show supported resolution, format and price. Wait for my model choice before preparing the task.”

Without model, all six friendly commands return choices without uploading media, reserving money or generating anything. kie_compare_models offers search and pagination (five entries by default, at most ten per page). Each call fetches live catalog/schema/pricing; it does not reuse a stale local list. Provider descriptions are claims, not measured quality ratings; generation speed remains unknown.

For video, the MCP reads an explicit duration parameter in seconds or one unambiguous length in seconds or minutes from the prompt, then reports each candidate as supported, unsupported, uncertain or automatic with the schema or provider description that supplies the limit. automatic means the model chooses the output length, so exact seconds are not guaranteed. Use next_cursor to review all catalog pages. Unclear limits are not counted as confirmed matches. input_type="video" searches Video-to-Video and declared video reference inputs; rows show task_types, is_video_to_video_model and video_input_semantics to distinguish those categories. A model can be catalogued as Video-to-Video and still expose a reference-video field; that field can guide generation without guaranteeing frame-accurate editing. Supply video_path/video_url to prepare a selected model. For combined input/output limits, input_video_duration_seconds is a user estimate; the MCP does not measure the clip locally.

With the chosen model, use dry_run=true for an exact preview. Image previews can upload your source to KIE; video previews can upload the clip. Metadata-only comparison does not upload media. Extra declared fields use model_input. Unknown or conditional prices outside reviewed profiles stay unknown; they are never treated as free. After the MCP warning, the user may explicitly accept that risk; the local ledger reserves the configured per-task limit, while KIE may charge more. Explicit auto_select=true delegates cheapest known-price selection among the first 20 candidates, not best quality. After completion, the MCP reports actual USD only if KIE returns costUsd; otherwise the final charge remains unknown and must not be inferred from credits or balance changes.

The paid path is preview → prepare → execute → wait/get_task → download. kie_prepare_task reserves shared budget; kie_execute_task needs the approval ID and unchanged model/input in the same MCP process/session. Execution rechecks schema/price. A timeout/unknown submission is not rejection: keep the liability and reconcile provider history before considering a retry.

kie_download_result(task_id=..., result_label="studio-photo") saves completed results inside the configured root: YYYY-MM-DD__studio-photo__image__provider-model__FULL_TASK_ID/<random-name>.<actual-extension>. The label is optional, limited to 48 UTF-8 bytes, letters/digits/spaces/underscores/ hyphens; it cannot be a path. Date is task creation in UTC, falling back to current UTC. Actual bytes determine type/extension. The response returns output_path and output_folder. Old directories are not renamed; re-downloads create new files.

Safety and limits

Defaults are $1/task, $5/session, $10/UTC day, $100 total and five concurrent tasks. Review owner settings before use. All processes share one SQLite ledger and must use identical stored budget policy. Do not delete/reset it or change its path to bypass spend; budget changes require deliberate owner reconciliation. Limits are conservative estimates, not a promise about provider charges. Confirm KIE-side spending caps/model policy separately, especially before unattended operation.

Uploads/downloads are disabled without explicit roots. Media signatures, bounded reads, anchored filesystem operations, fixed endpoints, HTTPS/public DNS pinning, redirect checks and approval/budget guards apply. Unknown prices need an owner's private exact-input quote or an explicit per-request user acknowledgement of the unknown-price risk. The latter reserves the configured per-task limit locally; actual KIE charges can be higher. Agents must explain this before setting accept_unknown_price=true. No MCP tool manages keys, caps, roots or policy.

An agent with shell/network access under the same OS account can operate outside MCP. This server does not isolate that agent or encrypt a plaintext secret file. For stronger isolation use a dedicated OS user/container with protected config and ledger, restricted mounts/egress and a key available only to MCP. See SECURITY.md for the full boundary and current limitations.

Development and status

See CONTRIBUTING.md for locked installation, offline checks and secret-safe contributions. No paid acceptance is required for ordinary local tests.

• PERSONAL_USE.md: tested personal workflows and remaining limitations.

• PRICE_SUPPORT.md: reviewed tariff profiles and expiry conditions.

• SAAS_READINESS.md: work needed for a multi-user backend.

• SECURITY_AUDIT.md, audit/: historical verification evidence.

Published reports are privacy-redacted historical evidence: live media links, private prompts, owner paths and raw diagnostic outputs are omitted. Reports describe the original test account/environment, not settings to copy or requirements to log into the original owner's account. Your installation uses your own keys, private files, budget policy and MCP client identity.