# kie-mcp-server

A remote MCP server that gives Claude three things: **generate a frame**, **generate a video clip from that frame**, and **check on a job that's still rendering**. Everything runs through your kie.ai account, so you pay kie.ai prices and use one credit wallet for all the models.

## Models wired up

| Friendly name | kie.ai model | Use it for |
|---|---|---|
| `nano-banana-2` | `nano-banana-2` | Default frame generator. Strong character consistency across a set of frames. |
| `nano-banana-2-lite` | `nano-banana-2-lite` | Cheap drafts. |
| `gpt-image-2` | `gpt-image-2-text-to-image` | Prompt adherence and text inside the image (titles, signage, posters). |
| `gpt-image-2-edit` | `gpt-image-2-image-to-image` | Restyle or fix an existing frame. |
| `seedance-2` | `bytedance/seedance-2` | Main video model. First+last frame control, reference images, native audio. |
| `seedance-2-fast` / `seedance-2-mini` | `bytedance/seedance-2-fast` / `-mini` | Faster/cheaper previews. |
| `seedance-2-5` | `bytedance/seedance-2-5` | Longer clips (up to ~30s), 1080p. |
| `veo3` / `veo3-fast` | `veo3` / `veo3_fast` | Veo 3.1. Best motion and dialogue, capped at 8s per clip. |

Model IDs live in `src/models.ts`. If kie.ai renames one, edit that file — nothing else changes. There's also a `kie_raw_task` tool that takes any model ID and raw input object, so you're never blocked waiting on a code change.

## Tools exposed

- `list_models` — what's available and what each is good at
- `generate_image` — prompt (+ optional reference images) → image URL, returned inline so Claude can look at it
- `generate_video` — prompt + optional `first_frame_url` / `last_frame_url` / `reference_image_urls` → MP4 URL
- `get_task` — poll a task ID that was still rendering
- `kie_raw_task` — any kie.ai model, raw input
- `check_credits` — remaining balance

## Setup

```bash
cp .env.example .env      # put your key in KIE_API_KEY
npm install
npm run build
npm start                 # http://localhost:3000/mcp
```

Get the API key at https://kie.ai/api-key and load credits at https://kie.ai/billing.

## Deploy

The connection to your server comes from Anthropic's cloud, not from your laptop, so it has to be reachable on the public internet over HTTPS. Localhost and anything behind a VPN won't work.

A `Dockerfile` and a `render.yaml` are included. Push the repo to GitHub, create a Render web service from it, set `KIE_API_KEY` and `MCP_PATH_SECRET` in the dashboard, deploy. Railway, Fly.io, or a Docker host all work the same way — anything that gives you an HTTPS URL.

**Set `MCP_PATH_SECRET`.** The server has no login, so the URL is the password. With `MCP_PATH_SECRET=8f2c1a9e4b` your endpoint becomes `https://your-host/mcp/8f2c1a9e4b`. Anyone who has that URL can spend your kie.ai credits.

## Connect it to Claude

In Claude, go to **Customize → Connectors**, click **+**, choose **Add custom connector**, and paste your full MCP URL including the secret path. Leave the OAuth fields blank. Custom connectors work on Free, Pro, Max, Team and Enterprise, though Free is limited to one, and on Team/Enterprise an Owner adds it first at the org level.

## Notes that will save you time

- **Output URLs expire in about 24 hours.** Download anything you want to keep.
- **Video takes 2–5 minutes.** A tool call can't block that long comfortably, so `generate_video` waits up to `wait_seconds` (default 180) and then hands back a task ID. Claude calls `get_task` to collect it.
- **Rate limit is roughly 20 new tasks per 10 seconds.** Rejected creates don't queue; the server surfaces a clear message on 429.
- **Frames must be reachable by URL.** Feed a `generate_image` output URL straight into `first_frame_url`. If you want to use your own local image, upload it somewhere public first (kie.ai has a file upload API if you'd rather keep it on their host).
- **This server generates clips, it doesn't edit them.** Stitching shots together, adding music, and cutting to length is a separate step — ffmpeg locally, or a second MCP server if you want Claude driving that too.