{
  "markdown": "# kie-mcp\n\nA comprehensive **Model Context Protocol** server for the [kie.ai](https://kie.ai) generation API. Gives Claude (and any MCP client) access to **54+ image models**, **95+ video models**, and **20+ audio tools** with deep model intelligence built in.\n\n## Why this exists\n\nMost MCPs are thin API wrappers. This one is different:\n\n- **Vertical profiles (NEW in 5.0)** — per-domain playbooks: `profile_brief` returns the intake questions a professional would ask, model routing per deliverable with live costs, per-model prompt formulas, and multi-tool workflows. Profiles double as MCP prompts (`/kie-art:architecture` in Claude Code). Verticals (10): architecture & interiors, video game assets, advertising & marketing, web & software product imagery, film & storyboarding, product photography & e-commerce, brand & graphic design, editorial & publishing, short-form social video, and audio branding & music.\n\n- **Deep research embedded** — Every major model has a `research` field with verdicts, prompt techniques, weaknesses, cost-efficiency analysis, and competitor comparisons. Researched by **Averiguare**, our model intelligence agent.\n- **Cost-aware** — Every model has pricing in credits and USD. The MCP tells you the cheapest option for your use case.\n- **Smart filtering** — `list_models filter=\"lip sync\"` or `filter=\"architecture\"` or `filter=\"cheapest video\"` — searches across capability tags, descriptions, AND research fields.\n- **Dual-mode transport** — stdio for local Claude Code, HTTP Streamable for remote Cowork/cloud usage.\n\n## What you can do with it\n\nJust ask Claude things like:\n- *\"Generate a brand presentation board for a perfume launch\"* — picks GPT Image 2 (best for text-heavy layouts)\n- *\"Make a 10s video of fruit scarecrows defending against crows, Pixar style\"* — recommends Veo 3.1 or Wan 2.7\n- *\"Generate music for a fantasy adventure game\"* — Suno V5\n- *\"Lip-sync this audio to my character image\"* — Kling AI Avatar or Infinitalk\n- *\"Upscale this video to 4K\"* — Veo 4K upscale or Topaz\n- *\"Replace the wall color in this room photo\"* — Flux Kontext Pro (best for surgical edits)\n\n## Model coverage\n\n### Image (54+)\n- **OpenAI**: GPT Image 2 (NEW), GPT-4o Image, GPT Image 1.5\n- **Google**: Nano Banana 2 / 2 Lite (NEW) / Pro / Edit / Original, Imagen 4 (Fast/Standard/Ultra)\n- **Black Forest Labs**: Flux Kontext Pro/Max, Flux 2 Pro/Flex\n- **ByteDance**: Seedream 3.0 / 4.0 / 4.5 / 5.0 Lite\n- **Alibaba**: Wan 2.7 Image / Image Pro\n- **Ideogram**: v3, Character, Edit, Remix, Reframe\n- **xAI Grok Imagine Image 2.0** (#2 Arena T2I + edit; free segment map → region-targeted edit chain; whole-image edits of ANY uploaded image)\n- **ByteDance Seedream 5.0 Pro** (NEW — T2I/I2I + layer decomposition: split any image into layer files)\n- **Qwen Image 3.0 / 3.0 Pro** (NEW — seed, negative prompts, 2K at the 1K price on standard)\n- **Others**: Qwen/Qwen2, Z-Image, Grok Imagine 1.x, Recraft, Topaz\n\n### Video (95+)\n- **Google Veo 3.1**: Quality / Fast / Lite (T2V + I2V), Extend, 1080p/4K upscale\n- **Alibaba HappyHorse**: 1.1 (NEW — T2V/I2V/R2V with native audio + 7-language lip-sync), 1.0 (T2V/I2V/R2V/Video Edit)\n- **ByteDance Seedance**: 2.5 (NEW — 30s single takes, live Aug 2026) / 2.0 / 2.0 Fast / 2.0 Mini / 1.5 Pro\n- **Kuaishou Kling**: 3.0 Omni \"O3\" (NEW — per-shot multi_prompt scripting, 4K, video Transformation), 3.0, 3.0 Turbo, 2.6, V2.5 Turbo, V2.1 Master/Pro/Standard, AI Avatar\n- **Alibaba Wan**: 3.0 + 3.0 Prime (NEW — unified prompt-or-media, audio), 2.7 (T2V/I2V/Edit/R2V), 2.6, 2.5, 2.2 Turbo, Animate\n- **MiniMax Hailuo**: H3 (NEW — 2K + native stereo audio, image+video+audio references, first→last-frame I2V), 2.3 Pro/Standard, 02 Pro/Standard\n- **xAI Grok Imagine**: Video 1.5 preview (NEW — I2V with native audio, cheapest audio video), T2V, I2V, Upscale, Extend\n- **Avatar / lip-sync**: OmniHuman 1.5 (NEW — audio-driven full-body avatar + free subject-detection utility), Volcengine Video Lip-Sync (NEW — re-dub existing footage), Kling AI Avatar, Infinitalk\n- **PixVerse V6** (NEW): T2V, I2V (viral templates), Transition (first→last morph), Fusion R2V (@ref_name), Extend — budget all-rounder with native audio\n- **Runway**: Aleph, Aleph Edit, Extend\n- **Others**: ByteDance V1 Pro/Lite, Topaz upscale\n\n### Audio (20+)\n- **Suno**: Music Gen, Extend, Cover, Add Instrumental/Vocals, Replace Section, Lyrics, Sounds, Sound Effects, MIDI, Music Video, Cover Art, Mashup, Persona, Timestamped Lyrics, Boost Style, Vocal Separation, WAV, Custom Voice cloning (experimental)\n- **ElevenLabs**: TTS (Turbo 2.5 + Multilingual V2), Text-to-Dialogue V3, Audio Isolation, Speech-to-Text\n- **Google Gemini TTS** (NEW): style-directed speech, 30 voices, 2-speaker dialogue, inline tone tags — ~4.2 cr/min\n\n### Utility\n- File upload (URL or base64)\n- Veo Extend, 1080p Upscale, 4K Upscale\n- Runway Extend\n- Task status, credit check, raw asset listing\n\n## Installation\n\n### Prerequisites\n- Node.js 18+\n- A kie.ai API key from [kie.ai/api-key](https://kie.ai/api-key)\n\n### Setup\n\n```bash\ngit clone https://github.com/YOUR_USERNAME/kie-mcp.git\ncd kie-mcp\nnpm install\n```\n\n### Run as stdio MCP (Claude Code, Claude Desktop)\n\nAdd to your Claude config (`~/.claude.json` for Claude Code, or your MCP client's equivalent):\n\n```json\n{\n  \"mcpServers\": {\n    \"kie-art\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/kie-mcp/server.mjs\"],\n      \"env\": {\n        \"KIE_API_KEY\": \"your-kie-ai-api-key\",\n        \"KIE_PROJECT_ROOT\": \"/optional/path/for/outputs\"\n      }\n    }\n  }\n}\n```\n\nOr use the Claude Code CLI:\n\n```bash\nclaude mcp add -s user kie-art /usr/bin/env -- KIE_API_KEY=your-key node /path/to/server.mjs\n```\n\n### Run as HTTP MCP (Cowork, remote clients)\n\n```bash\nKIE_API_KEY=your-key node server.mjs --http --port=3100\n```\n\nThen expose via ngrok / Cloudflare Tunnel / VPS deployment:\n```bash\nngrok http 3100\n```\n\nConfigure your MCP client to use the resulting URL:\n```json\n{\n  \"mcpServers\": {\n    \"kie-art\": {\n      \"type\": \"http\",\n      \"url\": \"https://your-tunnel.ngrok-free.dev/mcp\"\n    }\n  }\n}\n```\n\n## Environment variables\n\n| Variable | Required | Purpose |\n|---|---|---|\n| `KIE_API_KEY` | yes | Your kie.ai API key |\n| `KIE_PROJECT_ROOT` | no | Server-wide default for where generated files are saved (default: server cwd; files go to `$KIE_PROJECT_ROOT/kie/assets/raw/`). Per-call `download_dir` (absolute path) on any file-writing tool overrides this |\n| `KIE_MCP_PORT` | no | Port for HTTP mode (default: 3100) |\n| `KIE_CALLBACK_URL` | no | Callback URL sent with Suno generation requests (kie.ai requires the field; results are fetched by polling regardless). Defaults to an inert placeholder — set this only if you want to receive the callbacks yourself |\n| `KIE_MAX_CONCURRENT` | no | Max simultaneous task-creation calls (default 4). Excess parallel generations queue inside the server instead of hitting kie.ai's rate limits — parallel tool calls are safe |\n| `KIE_POLL_BUDGET_IMAGE` / `_VIDEO` / `_AUDIO` / `_SPEECH` | no | Blocking-mode polling budget per tool category, in seconds (defaults: 600 / 900 / 300 / 300). Per-call `max_wait_seconds` takes precedence. For long generations prefer `wait: false` (async mode): the tool returns the `task_id` immediately; poll with `check_task`, fetch with `download_result` |\n\n## Tools available\n\n```\ngenerate_image, generate_video, generate_music, generate_sfx,\ngenerate_tts, generate_gemini_tts, generate_dialogue, generate_sounds, generate_lyrics,\ngenerate_persona, generate_mashup, generate_cover_art,\ngenerate_midi, create_music_video,\nprepare_voice_clone, create_voice_clone, regenerate_voice_clone,\ncreate_omni_voice, create_omni_character,\nextend_music, cover_audio, upload_extend_audio,\nadd_instrumental, add_vocals, replace_section,\nconvert_to_wav, separate_vocals, boost_style,\nget_timestamped_lyrics, audio_isolation, speech_to_text,\nprofile_brief,\nlist_models, check_task, list_tasks, check_credits,\ndownload_result, list_raw_assets, upload_file,\ngrok_segment_map, grok_image_edit, seedream_layer_decompose,\nveo_extend, veo_upscale_1080p, veo_upscale_4k, runway_extend\n```\n\n## Smart model recommendations\n\nTry these queries in any MCP client:\n\n```\nlist_models filter=\"reasoning\"          # GPT-4o, Nano Banana, GPT Image 2\nlist_models filter=\"lip-sync\"           # OmniHuman 1.5, Volcengine, Kling Avatar, HappyHorse 1.1\nlist_models filter=\"multi-shot\"         # Kling 3.0/Turbo\nlist_models filter=\"cheapest video\"     # Grok Imagine 1.5, Wan Flash\nlist_models filter=\"alibaba\"            # HappyHorse 1.0/1.1 family\nlist_models filter=\"best visual quality\" # Veo Quality, Seedance 2.0\nlist_models filter=\"text rendering\"     # Ideogram v3, GPT Image 2\nlist_models filter=\"character\"          # Ideogram Character, Kling AI Avatar\n```\n\n## Architecture\n\n```\nserver.mjs                      # Transport, helpers, tool handlers (~2700 lines)\n├── createMcpServer()           # Factory for stdio + HTTP modes\n├── Tool handlers               # generate_*, list_*, etc.\n└── helpers                     # polling, recovery, pricing, validation, download\n\ndata/                           # Pure data, imported (and re-exported) by server.mjs\n├── registry-image.mjs          # MODEL_REGISTRY — image models (47+)\n├── registry-video.mjs          # VIDEO_MODEL_REGISTRY — video models (80+)\n├── registry-audio.mjs          # AUDIO_TOOLS_REGISTRY — audio tool metadata\n├── pricing.mjs                 # PRICING, PRICING_ESTIMATED, PROMPT_CAPS\n└── voices.mjs                  # ELEVENLABS_VOICES catalog\n```\n\nThe registries and pricing live in `data/*.mjs` so model-catalog changes are reviewable diffs instead of edits buried in a 5000-line file; `server.mjs` imports and re-exports them (tests and downstream keep importing from `server.mjs`).\n\nEach model entry has:\n- `name`, `description`, `capabilities` (tags), `pricing` (credits)\n- `aspectRatios`, `options` (with types and defaults)\n- `buildBody` / `buildInput` (request builders)\n- **`research`** (Averiguare verdicts, prompt techniques, weaknesses, comparisons, sources)\n\n## Development\n\n```bash\nnpm run check   # node --check server.mjs (syntax)\nnpm test        # offline unit tests for the pure helpers (test/*.test.mjs)\nnpm run smoke   # live end-to-end over MCP stdio — needs KIE_API_KEY\n                # (spends ~0 credits; uses the free subject-detection model)\n```\n\n`server.mjs` guards its side effects behind a main-module check, so it can be imported by tests (`test/unit.test.mjs`) to exercise the pure helpers without starting a server. `test/harness.mjs` is a reusable stdio JSON-RPC client for driving the real server in smoke/integration checks. CI ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)) runs the syntax check + unit tests on Node 20 and 22 for every push and PR.\n\n### Drift watch\n\nkie.ai changes things without notice — advertised prices, model availability, even API shapes. [`.github/workflows/drift-watch.yml`](.github/workflows/drift-watch.yml) runs [`scripts/drift-watch.mjs`](scripts/drift-watch.mjs) weekly (and on demand) to scan for it: paused/removed slugs, pricing that no longer matches the `PRICING` table, and new models in kie's catalog. Findings land in a single rolling GitHub issue. Add a `KIE_API_KEY` repo secret to enable the per-slug liveness probes (0 credits — empty-input validation errors); the pricing and new-model scans need no secret. Run locally with `node scripts/drift-watch.mjs`.\n\n## Releasing\n\nReleases are automated by [`.github/workflows/release.yml`](.github/workflows/release.yml). To cut a release:\n\n1. Bump the version in `package.json`, `server.json` (both the top-level `version` and `packages[0].version`), and `server.mjs` (`SERVER_INFO` + the `/health` handler), and add a `## [X.Y.Z]` section to `CHANGELOG.md`. Merge to `main`.\n2. Tag and push:\n   ```bash\n   git tag vX.Y.Z && git push origin vX.Y.Z\n   ```\n\nThe workflow verifies the tag matches every in-repo version string, publishes to npm with provenance (`NPM_TOKEN` repo secret), and creates the GitHub Release using the matching CHANGELOG section as the notes. A tag whose version doesn't match the code fails fast without publishing. `workflow_dispatch` is an emergency manual publish of the current `package.json` version.\n\n## Credits\n\n- Built with the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)\n- Powered by [kie.ai](https://kie.ai) — affordable unified API for 100+ AI models\n- Model intelligence by **Averiguare** — *\"No sabes hasta que averiguas — y averiguo en todas partes.\"*\n\n## License\n\nMIT\n",
  "bytes": 12569,
  "sha": "42c0ff07a649b5ed261c6885ef332b912d54d905039158091bf977ff34d0a9b7",
  "repo_slug": "elibarnett/kie-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_elibarnett_kie_mcp_2c4c7a43/readme"
}