kie-mcp

kie-mcp

面向 kie.ai 生成 API 的综合 Model Context Protocol 服务。让 Claude（以及任何 MCP 客户端）能够使用内置深度模型智能，访问 60+ 种图像模型、85+ 种视频模型和 20+ 种音频工具。

为什么要做这个项目

大多数 MCP 都只是简单的 API 封装。这个项目则有所不同：

• 垂直领域配置（5.0 版新增） — 按领域提供实用指南：profile_brief 会返回专业人士会提出的需求问题、针对每项交付成果的模型路由及实时费用、各模型的提示词公式，以及多工具工作流。这些配置还可作为 MCP 提示词使用（在 Claude Code 中输入 /kie-art:architecture）。涵盖 10 个垂直领域：建筑与室内设计、电子游戏素材、广告与营销、网站与软件产品图像、电影与分镜、产品摄影与电子商务、品牌与平面设计、编辑与出版、短视频社交内容，以及音频品牌与音乐。

• 内置深度研究 — 每个主要模型都有一个 research 字段，包含评估结论、提示词技巧、弱点、成本效益分析和竞品对比。研究由我们的模型智能 Agent Averiguare 完成。

• 关注成本 — 每个模型都标注了积分和美元价格。MCP 会告诉你适用于当前场景的最便宜选项。

• 智能筛选 — 使用 list_models filter="lip sync"、filter="architecture" 或 filter="cheapest video" 进行搜索，可匹配能力标签、描述和研究字段。

• 双模式传输 — 本地 Claude Code 使用 stdio，远程 Cowork／云端使用 HTTP Streamable。

可以用它做什么

只需向 Claude 提出以下请求：

• “为香水发布会生成一张品牌展示板” — 选择 GPT Image 2（最适合文本密集的布局）
• “制作一个 10s 的视频，展现水果稻草人以 Pixar 风格抵御乌鸦” — 推荐 Veo 3.1 或 Wan 2.7
• “为奇幻冒险游戏创作音乐” — Suno V5
• “让这段音频与我的角色图像对口型” — Kling AI Avatar 或 Infinitalk
• “将这段视频放大到 4K” — Veo 4K upscale 或 Topaz
• “替换这张房间照片中的墙面颜色” — Flux Kontext Pro（最适合精细编辑）

模型覆盖范围

图像（60+）

• OpenAI：GPT Image 2.5 Flare / Sunburst（新增 — 1K-4K，透明背景）、GPT Image 2、GPT-4o Image、GPT Image 1.5
• Google：Nano Banana 2.1（新增，4 cr）、Nano Banana 2 / 2 Lite / Pro / Edit / Original、Imagen 4（Fast/Standard/Ultra）
• Black Forest Labs：FLUX 3 Klein T2I + Edit（新增，1.6 cr）、Flux Kontext Pro/Max、Flux 2 Pro/Flex
• ByteDance：Seedream 3.0 / 4.0 / 4.5 / 5.0 Lite
• Alibaba：Wan 2.7 Image / Image Pro
• Ideogram：v3、Character、Edit、Remix、Reframe
• xAI Grok Imagine Image 2.0（Arena T2I + 编辑排名第 2；免费分区图 → 区域定向编辑链；可对任何上传图像进行整图编辑）
• ByteDance Seedream 5.0 Pro（新增 — T2I/I2I + 图层分解：将任意图像拆分为图层文件）
• Qwen Image 3.0 / 3.0 Pro（新增 — seed、负面提示词；标准版以 1K 价格生成 2K 图像）
• Qwen Image 2.1（新增 — 透明背景、蒙版修复、10 张参考图合成）
• 其他：Qwen/Qwen2、Z-Image、Grok Imagine 1.x、Recraft、Topaz

视频（85+）

• Google Veo 3.1：Quality / Fast / Lite（T2V + I2V）、扩展、1080p/4K 放大
• Alibaba HappyHorse：1.1（全新 — T2V/I2V/R2V，支持原生音频 + 7 种语言唇形同步）、1.0（T2V/I2V/R2V/视频编辑）
• ByteDance Seedance：2.5（30 秒单镜头、1080p、草稿→1080p 升级）/ 2.0 / 2.0 Fast / 2.0 Mini（1.5 Pro 已于 2026 年 10 月在上游停用）
• Kuaishou Kling：4.0（全新 — 参考图转视频，支持命名的 @subjects/voices/video refs、关键帧转视频、3-30 秒）、3.0 Omni「O3」（全新 — 支持逐镜头 multi_prompt 脚本、4K、视频转换）、3.0、3.0 Turbo、2.6、V2.5 Turbo、V2.1 Master/Pro/Standard、AI Avatar
• Alibaba Wan：3.0 + 3.0 Prime（全新 — 统一支持提示词或媒体输入、音频）、2.7（T2V/I2V/编辑/R2V）、2.6、2.5、2.2 Turbo、Animate
• Google Gemini Omni：Video + 1.1 Flash（全新 — 首帧→末帧模式，360p-4K；支持图像/语音/视频/角色参考）
• MiniMax Hailuo：H3（全新 — 2K + 原生立体声音频、图像+视频+音频参考、I2V 首帧→末帧）、2.3 Pro/Standard、02 Pro/Standard
• xAI Grok Imagine：Video 1.5 preview（全新 — 支持原生音频的 I2V，最便宜的音频视频）、T2V、I2V、放大、扩展
• Avatar / 唇形同步：OmniHuman 2.0（全新 — 14 cr/s，支持最长 5 分钟音频）、OmniHuman 1.5（全新 — 音频驱动的全身 Avatar + 免费的主体检测和人物识别实用工具）、Volcengine Video Lip-Sync（全新 — 为现有视频重新配音）、Kling AI Avatar、Infinitalk
• PixVerse V6 / V6 Max（V6 Max 全新：更高质量的 T2V/I2V）：T2V、I2V（热门模板）、Transition（首帧→末帧变形）、Fusion R2V（@ref_name）、扩展——支持原生音频的高性价比全能工具
• Runway：Aleph、Aleph Edit、扩展
• 其他：ByteDance V1 Pro/Lite、Topaz 放大

音频（20+）

• Suno：音乐生成、扩展、翻唱、添加伴奏/人声、替换片段、歌词、声音、音效、MIDI、音乐视频、封面图、混搭、Persona、带时间戳的歌词、风格增强、人声分离、WAV、自定义语音克隆（实验性）
• ElevenLabs：TTS（Turbo 2.5 + Multilingual V2）、文本转对话 V3、音频隔离、语音转文本
• Google Gemini TTS（全新）：风格定向语音、30 种声音、双人对话、内联语气标签——约 4.2 cr/min

实用工具

• 文件上传（URL 或 base64）
• Veo 扩展、1080p 放大、4K 放大
• Runway 扩展
• 任务状态、额度检查、原始素材列表

安装

前置条件

• Node.js 18+
• 从 kie.ai/api-key 获取 kie.ai API 密钥

设置

git clone https://github.com/YOUR_USERNAME/kie-mcp.git
cd kie-mcp
npm install

作为 stdio MCP 运行（Claude Code、Claude Desktop）

添加到 Claude 配置（Claude Code 使用 ~/.claude.json，或使用 MCP 客户端对应的配置文件）：

{
  "mcpServers": {
    "kie-art": {
      "command": "node",
      "args": ["/absolute/path/to/kie-mcp/server.mjs"],
      "env": {
        "KIE_API_KEY": "your-kie-ai-api-key",
        "KIE_PROJECT_ROOT": "/optional/path/for/outputs"
      }
    }
  }
}

或使用 Claude Code CLI：

claude mcp add -s user kie-art /usr/bin/env -- KIE_API_KEY=your-key node /path/to/server.mjs

作为 HTTP MCP 运行（Cowork、远程客户端）

HTTP 模式需要 bearer 令牌，默认监听 127.0.0.1。

export KIE_MCP_AUTH_TOKEN=$(openssl rand -hex 32)
KIE_API_KEY=your-key node server.mjs --http --port=3100

使用 URL 和令牌配置 MCP 客户端：

{
  "mcpServers": {
    "kie-art": {
      "type": "http",
      "url": "http://127.0.0.1:3100/mcp",
      "headers": { "Authorization": "Bearer <your KIE_MCP_AUTH_TOKEN>" }
    }
  }
}

如需远程访问，请将其置于隧道（ngrok / Cloudflare Tunnel）或反向代理之后。服务仍在回环地址上运行，由隧道将请求转发至此处。将隧道的主机名添加到 KIE_MCP_ALLOWED_HOSTS。请将令牌视同密码：任何持有令牌的人都可以消耗你的 kie 额度，并从服务所在磁盘上传媒体文件。

**安全提示（5.2.2）：**较早版本在 0.0.0.0 上运行 HTTP 模式，且没有身份验证，并设置了 Access-Control-Allow-Origin: *。任何在浏览器中打开的网页，或任何持有隧道 URL 的人，都可以调用这些工具，包括通过 upload_file 读取本地文件。如果使用 --http，请升级。

环境变量

变量	必需	用途
KIE_API_KEY	是	你的 kie.ai API 密钥
KIE_PROJECT_ROOT	否	服务器级默认路径，用于保存生成的文件（默认：服务器当前工作目录；文件保存到 $KIE_PROJECT_ROOT/kie/assets/raw/）。任何文件写入工具调用中的 download_dir（绝对路径）都会覆盖此设置
KIE_MCP_PORT	否	HTTP 模式的端口（默认：3100）
KIE_SUNO_API	否	legacy 会将 Suno 工具发送到 kie 的旧版 Suno 端点。自 5.5.0 起，默认使用 kie 的新版市场 API（ai-music-api/*），该 API 会报告实际扣除的额度。MIDI、混搭和声音克隆始终使用旧端点
KIE_ELEVENLABS_ENABLED	否	设为 1 可重新启用 ElevenLabs 工具（自 5.4.0 起暂停，因为 kie 的 ElevenLabs 集成无法正常工作）
KIE_MAX_CREDITS_PER_CALL	否	每次工具调用的默认额度上限。预估额度超出上限的调用会在提交前被拒绝；单次调用的 max_credits 会覆盖此设置
KIE_MCP_AUTH_TOKEN	HTTP 模式	HTTP 客户端必须发送的 Bearer 令牌（Authorization: Bearer …）。未设置此令牌时，服务器会拒绝以 HTTP 模式启动
KIE_MCP_HOST	否	HTTP 绑定地址（默认 127.0.0.1）。仅在容器内或防火墙后设置为 0.0.0.0
KIE_MCP_ALLOWED_HOSTS	否	允许接受的额外 Host 标头名称，以逗号分隔（例如你的隧道主机名）。在环回地址上始终接受 localhost 名称；其他主机名会被拒绝，以防止 DNS 重绑定
KIE_MCP_ALLOWED_ORIGINS	否	允许调用服务器的浏览器来源，以逗号分隔（CORS）。带有其他 Origin 标头的请求会被拒绝。非浏览器 MCP 客户端不会发送 Origin，因此不受影响
KIE_CALLBACK_URL	否	随 Suno 生成请求发送的回调 URL（kie.ai 要求提供此字段；无论如何，结果都会通过轮询获取）。默认使用无实际作用的占位值——只有想自行接收回调时才设置此项
KIE_MAX_CONCURRENT	否	同时创建任务的最大调用数（默认 4）。超出的并行生成任务会在服务器内部排队，而不会触发 kie.ai 的速率限制——并行工具调用是安全的
KIE_POLL_BUDGET_IMAGE / _VIDEO / _AUDIO / _SPEECH	否	阻塞模式下各工具类别的轮询时长上限，以秒为单位（默认值：600 / 900 / 300 / 300）。单次调用的 max_wait_seconds 优先级更高。对于耗时较长的生成，建议使用 wait: false（异步模式）：工具会立即返回 task_id；使用 check_task 轮询，使用 download_result 获取结果

可用工具

generate_image, generate_video, generate_music, generate_sfx,
generate_tts, generate_gemini_tts, generate_dialogue, generate_sounds, generate_lyrics,
generate_persona, generate_mashup, generate_cover_art,
generate_midi, create_music_video,
prepare_voice_clone, create_voice_clone, regenerate_voice_clone,
create_omni_voice, create_omni_character,
extend_music, cover_audio, upload_extend_audio,
add_instrumental, add_vocals, replace_section,
convert_to_wav, separate_vocals, boost_style,
get_timestamped_lyrics, audio_isolation, speech_to_text,
profile_brief,
list_models, check_task, list_tasks, check_credits, spend_report,
download_result, list_raw_assets, upload_file,
grok_segment_map, grok_image_edit, seedream_layer_decompose,
veo_extend, veo_upscale_1080p, veo_upscale_4k, runway_extend

费用控制

kie 按调用计费，部分调用费用较高（1080p/4K 视频、图层拆分、1080p 草稿升级）。每个付费工具都有两个可选参数：

• estimate_only: true 根据已公布的费率返回预估额度，包括分辨率/尺寸档位和视频时长，但不会提交任何内容。
• max_credits: N 当预估额度超出 N 时拒绝提交。设置 KIE_MAX_CREDITS_PER_CALL 可为每次调用应用默认上限。

generate_video { model: "bytedance/seedance-2-5", model_options: { resolution: "1080p", duration: 10 }, estimate_only: true }
→ 💰 ~1580 credits (~$7.90) — 158 cr/s × 10s. Nothing was submitted.

spend_report 会显示额度的去向。它按模型或日期汇总服务器过去 N 天的任务历史，使用 kie 实际扣除的额度（会查询任何缺失的额度），并单独列出失败的任务。

智能模型推荐

在任何 MCP 客户端中尝试以下查询：

list_models filter="reasoning"          # GPT-4o, Nano Banana, GPT Image 2
list_models filter="lip-sync"           # OmniHuman 1.5, Volcengine, Kling Avatar, HappyHorse 1.1
list_models filter="multi-shot"         # Kling 3.0/Turbo
list_models filter="cheapest video"     # Grok Imagine 1.5, Wan Flash
list_models filter="alibaba"            # HappyHorse 1.0/1.1 family
list_models filter="best visual quality" # Veo Quality, Seedance 2.0
list_models filter="text rendering"     # Ideogram v3, GPT Image 2
list_models filter="character"          # Ideogram Character, Kling AI Avatar

架构

server.mjs                      # Transport, helpers, tool handlers (~2700 lines)
├── createMcpServer()           # Factory for stdio + HTTP modes
├── Tool handlers               # generate_*, list_*, etc.
└── helpers                     # polling, recovery, pricing, validation, download

data/                           # Pure data, imported (and re-exported) by server.mjs
├── registry-image.mjs          # MODEL_REGISTRY — image models (47+)
├── registry-video.mjs          # VIDEO_MODEL_REGISTRY — video models (80+)
├── registry-audio.mjs          # AUDIO_TOOLS_REGISTRY — audio tool metadata
├── pricing.mjs                 # PRICING, PRICING_ESTIMATED, PROMPT_CAPS
└── voices.mjs                  # ELEVENLABS_VOICES catalog

模型注册表和定价位于 data/*.mjs 中，因此模型目录的变更会以易于审查的差异呈现，而不是埋在一个 5000 行的文件中；server.mjs 会导入并重新导出它们（测试和下游项目仍从 server.mjs 导入）。

每个模型条目包含：

• name、description、capabilities（标签）、pricing（额度）
• aspectRatios、options（含类型和默认值）
• buildBody / buildInput（请求构造器）
• research（Averiguare 的评估结论、提示词技巧、弱点、比较结果、来源）

开发

npm run check   # node --check server.mjs (syntax)
npm test        # offline unit tests for the pure helpers (test/*.test.mjs)
npm run smoke   # live end-to-end over MCP stdio — needs KIE_API_KEY
                # (spends ~0 credits; uses the free subject-detection model)

server.mjs 会通过主模块检查来控制副作用，因此可由测试（test/unit.test.mjs）导入，以测试纯辅助函数而不启动服务。test/harness.mjs 是一个可复用的 stdio JSON-RPC 客户端，可用于驱动真实服务进行冒烟测试和集成检查。CI（.github/workflows/ci.yml）会在每次推送和 PR 时，使用 Node 20 和 22 运行语法检查和单元测试。

实时检查（每周运行一次）

npm run live-check   # KIE_API_KEY from env, else ~/.claude.json kie-art

运行整套维护流程约需 2 分钟，并生成 live-check-report.md：

1. **文档索引差异：**自上次运行以来 docs.kie.ai 新增或删除的页面。这是最可靠的新模型信号。
2. **漂移监控与实时 slug 探测：**价格漂移、已暂停或已移除的模型、目录变更。
3. **监控列表：**对上游曾发生故障的模型（例如 ElevenLabs）进行真实调用，以便了解何时可以重新启用它们。失败调用不消耗积分。
4. npm audit 摘要。

请在自己的机器上运行。GitHub 托管的运行器无法获取 kie.ai 页面，因此下方的定时工作流只会报告其无法进行检查。

漂移监控

kie.ai 可能会不作通知地更改内容，包括宣传价格、模型可用性，甚至 API 结构。.github/workflows/drift-watch.yml 会每周（也可按需）运行 scripts/drift-watch.mjs 进行扫描，检查已暂停或已移除的 slug、不再与 PRICING 表匹配的价格，以及 kie 目录中的新模型。发现结果会汇总到一个持续更新的 GitHub issue 中。添加 KIE_API_KEY 仓库密钥即可启用逐 slug 存活探测（0 积分——空输入验证错误）；价格和新模型扫描无需密钥。在本地运行：node scripts/drift-watch.mjs。

发布

发布流程由 .github/workflows/release.yml 自动执行。要发布新版本：

1. 更新 package.json、server.json（顶层的 version 和 packages[0].version）以及 server.mjs（SERVER_INFO 和 /health 处理器）中的版本，并在 CHANGELOG.md 中添加 ## [X.Y.Z] 小节。合并到 main。
2. 创建并推送标签：

   git tag vX.Y.Z && git push origin vX.Y.Z
   

工作流会验证标签是否与仓库内的所有版本字符串一致，使用来源证明将包发布到 npm（需要 NPM_TOKEN 仓库密钥），并使用对应的 CHANGELOG 小节作为说明创建 GitHub Release。若标签版本与代码不匹配，流程会立即失败，不会发布。workflow_dispatch 用于紧急手动发布当前 package.json 版本。

致谢

• 基于 MCP TypeScript SDK 构建
• 由 kie.ai 提供支持——面向 100 多种 AI 模型的实惠统一 API
• 模型洞察由 Averiguare 提供——"No sabes hasta que averiguas — y averiguo en todas partes."

许可证

MIT