KickArt MCP Server

这是一个基于 TypeScript + Node.js + STDIO 的 KickArt MCP Server，同时提供面向 Skill / 脚本调用的命令行工具。

MCP Server

MCP Server 入口为 kickart-open-mcp，仅注册以下 MCP tools：

• upload_media：上传本地图片、视频素材，返回 media_id 和 URL
• submit_viral_task：提交爆款裂变任务，返回 task_id
• submit_marketing_task：提交一键成片任务，返回 task_id
• query_task：统一查询爆款裂变/一键成片任务状态；需显式传入 source，任务完成后默认自动发布成片到 KickArt，并返回本地存储的 open api response JSON 路径

这些 MCP tools 从 master 版本原样搬入，使用 ACCESS_KEY 和 SECRET_KEY 进行 AK/SK 鉴权。

STDIO 配置

{
  "mcpServers": {
    "kickart-open-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@volcengine/kickart-open-mcp@latest"
      ],
      "env": {
        "ACCESS_KEY": "${ACCESS_KEY}",
        "SECRET_KEY": "${SECRET_KEY}"
      }
    }
  }
}

MCP 调用建议

• 本地文件先调用 upload_media 得到 media_id，再传给 submit_viral_task 或 submit_marketing_task。
• 公网 HTTP(S) URL 可直接传入 ref_video、product_images、model_images、location_images、user_images、user_videos 等字段。
• query_task 需要同时传入 task_id 和 source；一键成片传 kickart_ai_material，爆款裂变传 ad_variations。
• query_task 默认自动发布任务产物，并将 open api 原始响应保存到本地 JSON 文件。

CLI

CLI 入口为 kickart-open-cli，直接调用内部 service 方法，不启动 MCP Server。CLI 提供以下命令：

• ai_beauty：AI 美颜，支持单图、图片 URL、多 URL 和压缩包批处理
• upload_material_v2：上传本地素材到 KickArt 对象存储，返回上传回执
• create_material_v2：根据上传回执创建 KickArt 媒资，返回 media_id
• search_material_v2：根据 media_id 查询媒资详情和原始下载地址
• material_pipeline_v2：一站式上传、创建并查询本地素材
• submit_viral_task_v2：提交爆款裂变任务，返回 task_id
• submit_high_similarity_task_v2：提交高相似度爆款复刻任务，返回 task_id
• submit_marketing_task_v2：提交一键成片任务，返回 task_id
• query_task_v2：统一查询爆款裂变/一键成片任务状态；需显式传入 source，任务完成后默认通过 /openapi/ai_effect/media/save_url 同步产物到 KickArt，并返回本地存储的 open api response JSON 路径
• auth_login：启动 OAuth 设备授权并立即返回授权链接，或使用已有 token 登录
• auth_complete：用户完成网页授权后，单次请求 token 并完成登录
• auth_logout：删除本地保存的 OAuth 登录凭据
• auth_token：读取当前生效的 OAuth token

带 _v2 后缀的命令为当前版本实现，支持 OAuth Bearer 鉴权；ai_beauty 仅提供 CLI，不注册为 MCP tool。

本地调试

npm install
cp .env.example .env
npm run build
node dist/index.js

只做类型检查：

npm run typecheck

使用 MCP Inspector：

npm run inspect

Skill CLI 调用

每个 CLI 命令都支持 --help 查看含义、必填参数和可选参数。

查看全部命令：

kickart-open-cli --help

查看单个工具说明：

kickart-open-cli submit_marketing_task_v2 --help

AI 美颜仅提供 CLI，与其他 KickArt 能力共用 OAuth 鉴权。可先启动设备授权，手动访问输出的链接并在授权完成后执行确认命令，或设置已有 token：

kickart-open-cli auth login
# 或：export KICKART_TOKEN=your_oauth_token

kickart-open-cli ai_beauty \
  --file /absolute/path/to/photo.jpg \
  --output /absolute/path/to/result.json

--file 还支持单个图片 URL、逗号分隔的多个图片 URL，以及 zip、tar、tar.gz、tar.bz2、tar.xz 压缩包。本地图片统一通过 material_pipeline_v2 上传并转换为原始下载 URL；批量模式会下载处理后的图片，并在结果 JSON 同目录生成 ZIP 文件。

示例：查询一键成片任务：

kickart-open-cli query_task_v2 --task-id your_task_id --source kickart_ai_material --auto-publish false

示例：本地源码调试 CLI：

npm run cli -- query_task_v2 --task-id your_task_id --source ad_variations --auto-publish false

查看单个工具的参数说明：

npm run cli -- submit_marketing_task_v2 --help

OAuth 设备授权登录（第一个命令立即返回授权链接且不会轮询；网页授权完成后执行第二个命令获取 token）：

kickart-open-cli auth login
# 完成网页授权后执行
kickart-open-cli auth complete

从标准输入导入已有 token：

printf '%s' "$KICKART_TOKEN" | kickart-open-cli auth login --with-token

读取 token 或退出登录：

kickart-open-cli auth token
kickart-open-cli auth logout

OAuth 凭据优先保存到系统凭据存储；系统未安装可选的 keytar 模块或使用 --insecure-storage 时，凭据保存到 ~/.kickart/hosts.json，文件权限为 0600。环境变量 KICKART_TOKEN 始终优先于已保存凭据。 设备授权登录会保存 /oauth/token 返回的 access token 和 refresh token；成功响应缺少任一 token 时登录或刷新失败。客户端会在 access token 临近过期时自动调用 /oauth/token 刷新，并保存服务端轮换后的新 refresh token。refresh token 从首次授权签发时起固定有效 30 天，后续轮换不会延长或续期；过期或失效后会清理本地凭据。手动导入的 KICKART_TOKEN 无法自动刷新。 除 OAuth 登录、换取 token 接口外，所有 KickArt 功能接口均使用当前 OAuth token 进行 Bearer 鉴权，请先完成登录。

示例：使用对象存储媒资流水线：

kickart-open-cli material_pipeline_v2 --file-path /absolute/path/to/ref.mp4

也可以分步执行：

kickart-open-cli upload_material_v2 --file-path /absolute/path/to/ref.mp4
kickart-open-cli create_material_v2 --type video --data '{"file_name":"ref.mp4","id":"...","etag":"...","size":1024}'
kickart-open-cli search_material_v2 --media-ids your_media_id

示例：提交一键成片：

kickart-open-cli submit_marketing_task_v2 \
  --duration 15 \
  --product-url https://example.com/item \
  --user-images /absolute/path/to/product.jpg \
  --aspect-ratio 9:16 \
  --language zh

示例：使用本地参考视频提交爆款裂变：

kickart-open-cli submit_viral_task_v2 \
  --ref-video /absolute/path/to/ref.mp4 \
  --product-url https://example.com/item

示例：提交高相似度爆款复刻：

kickart-open-cli submit_high_similarity_task_v2 \
  --ref-video /absolute/path/to/ref.mp4 \
  --replace-images /absolute/path/to/role.png,/absolute/path/to/product.png \
  --prompt "将视频中的 xx 角色替换为图1，xx 商品替换为图2，场景改为海边。" \
  --language zh

未传 --template-id 时，高相似度爆款复刻默认使用模板 1028571394。

submit_viral_task_v2 和 submit_marketing_task_v2 的图片、视频入参统一接受本地文件路径或 HTTP(S) URL。本地文件会在内部自动执行 material_pipeline_v2 并转换为原始下载 URL。

NPM 发布

npm publish --access public

如果版本已存在：

npm version patch --no-git-tag-version
npm publish --access public

调用建议

• 本地图片或视频路径可直接传入 ref_video、product_images、model_images、location_images、user_images、user_videos 等字段，工具会自动上传并转换为 URL。
• 公网 HTTP(S) URL 可直接传入上述图片或视频字段。
• 一键成片 template_id 优先通过对话参数传入；未传时默认使用 978755842。
• query_task_v2 需要同时传入 task_id 和 source；一键成片传 kickart_ai_material，爆款裂变传 ad_variations。
• query_task_v2 每次查询都会将 open api 原始响应保存到本地 JSON 文件；任务完成后会返回最终文件路径。
• 一键成片若接口新增字段，优先通过 extra_params 透传，避免频繁改工具 schema。