MCP 接入文档

适用于片语 v1.2.0 及以上版本 · 最近更新：2026 年 8 月

片语内置一个 MCP（Model Context Protocol）服务器。开启后，本机的 AI agent（Kimi CLI、Claude Code 等）可以直接调用片语的视频制作能力（宣传片 / vlog / 口播 / 教程 / 卡点混剪）：一句话全自动流水线（run_auto_pipeline）、视频体裁切换（set_video_type）、读取与修改故事板、长素材挖高光（mine_highlights / apply_cut_list）、视频跟踪稳定（stabilize_clip / set_stabilization）、图库搜索与文生图取材、查看画面（预览帧 / 素材抽帧 / 截图，以图片原生返回）、触发渲染、审片与音频体检——共 68 个工具，与片语内置 AI 助手完全同源。

前置条件

1. 片语已安装并正在运行（工具在应用界面进程内执行）；
2. 打开「设置 → Agent 接入（MCP）」，开启「启用 MCP 服务」，状态行显示「运行中」；
3. 如需 agent 触发渲染，请先在「设置 → 默认输出目录」里配置导出目录。

方式一：一键接入（推荐）

在「设置 → Agent 接入（MCP）」的「一键接入」区域，点击对应 agent 的按钮即可，片语会自动把配置（含地址与 Token）写入该 agent 的配置文件，写入前自动备份原配置：

• Kimi Code CLI：写入用户级配置 ~/.kimi-code/mcp.json；
• Claude Code：合并写入 ~/.claude.json 的 mcpServers；
• Codex CLI：合并写入 ~/.codex/config.toml 的 [mcp_servers]；
• OpenClaw：合并写入 ~/.openclaw/openclaw.json 的 mcp.servers；
• ZCode CLI：合并写入 ~/.zcode/cli/config.json 的 mcp.servers；
• DeepSeek Harness：合并写入 ~/.dsh/cordis.patch.yml 的插件 patch 列表（装载官方 MCP client 插件接入）。

完成后重启 agent（或新建会话）即可使用，工具名形如 mcp__pianyu__get_templates。

方式二：让 agent 自己接入（复制接入指令）

点击设置页的「复制接入指令」，会得到一段包含本页地址、服务地址与 Token 的指令，直接粘贴给任意支持网页读取的 AI agent，它就能依照本页文档自行完成配置。指令形如：

请依照 https://studio.dwphoto.top/videotool/mcp.html 的文档，帮我接入"片语"的 MCP 服务。
服务地址：http://127.0.0.1:17890/mcp，Token：<你的接入 Token>。

方式三：手动配置

Kimi Code CLI

编辑用户级配置 ~/.kimi-code/mcp.json（Windows：C:\Users\<用户名>\.kimi-code\mcp.json），在 mcpServers 中加入：

{
  "mcpServers": {
    "pianyu": {
      "url": "http://127.0.0.1:17890/mcp",
      "headers": {
        "Authorization": "Bearer <设置页里的接入 Token>"
      }
    }
  }
}

Claude Code

编辑 ~/.claude.json，在顶层 mcpServers 中加入：

{
  "mcpServers": {
    "pianyu": {
      "type": "http",
      "url": "http://127.0.0.1:17890/mcp",
      "headers": {
        "Authorization": "Bearer <设置页里的接入 Token>"
      }
    }
  }
}

Codex CLI

编辑 ~/.codex/config.toml（Windows：C:\Users\<用户名>\.codex\config.toml），在文件末尾追加（TOML 格式，注意不要加 type 键）：

[mcp_servers.pianyu]
url = "http://127.0.0.1:17890/mcp"
http_headers = { "Authorization" = "Bearer <设置页里的接入 Token>" }

ZCode CLI

编辑 ~/.zcode/cli/config.json（Windows：C:\Users\<用户名>\.zcode\cli\config.json），在 mcp.servers 中加入（严格 JSON：该文件校验严格，条目里出现未知键会导致整个 server 被静默丢弃，请只保留下列键）：

{
  "mcp": {
    "servers": {
      "pianyu": {
        "type": "http",
        "url": "http://127.0.0.1:17890/mcp",
        "headers": {
          "Authorization": "Bearer <设置页里的接入 Token>"
        },
        "enabled": true
      }
    }
  }
}

DeepSeek Harness

DeepSeek Harness 通过官方 MCP client 插件接入，配置在 ~/.dsh/cordis.patch.yml 的 patch 列表中追加一行（结构较特殊，推荐直接使用「一键接入」；一键写入会把工具超时对齐到 180 秒，与片语渲染时长匹配）：

- insert:
  - id: mcp-pianyu
    name: '@deepseek-ai/dsh-mcp-client'
    config:
      serverName: pianyu
      transport: streamable-http
      url: "http://127.0.0.1:17890/mcp"
      headers:
        Authorization: "Bearer <设置页里的接入 Token>"
      toolCallTimeoutMs: 180000

OpenClaw

编辑 ~/.openclaw/openclaw.json，在 mcp.servers 中加入：

{
  "mcp": {
    "servers": {
      "pianyu": {
        "url": "http://127.0.0.1:17890/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer <设置页里的接入 Token>"
        }
      }
    }
  }
}

仅支持 stdio 的客户端

用 mcp-remote 做 stdio → HTTP 桥接：

{
  "mcpServers": {
    "pianyu": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:17890/mcp",
        "--header",
        "Authorization: Bearer <设置页里的接入 Token>"
      ]
    }
  }
}

工具清单（68 个）

工具 schema 与片语内置 AI 助手同源，片语升级新增工具时客户端无需改动配置。

推荐工作流

首次接入先调用 get_workflow_guide，获取按工程体裁组装的成片工作流指南（体裁分册剧本 + 三阶段：素材采集 → 成片渲染 → 发布准备，含推荐调用序列、前置条件清单与调参纪律），与片语内置 AI 助手同源（set_video_type 切换体裁后返回对应分册）；MCP initialize 握手响应的 instructions 字段也带简要指引。用户只想尽快拿到成片时，直接调用 run_auto_pipeline 一句话全自动（组稿 → 取材 → 配音 → 渲染 → 审片 → 修复 → 交付物，用 get_app_status 轮询进度）；需要精细控制每个环节时再走分步工具。要点务必记住：

• 先采素材再成片：用 list_capture_sources / take_screenshot / start_screen_recording / stop_screen_recording 主动引导用户录屏采集（停录自动入段、可掐头去尾），view_media_frames 抽帧验收，素材齐备后再进入成片阶段；
• set_storyboard 会清空素材：它是整体重建，只在空故事板搭骨架时安全；已有素材的片段一律改用 update_segment 逐段修改；
• 渲染前先确认输出目录：用户需在「设置 → 默认输出目录」配置，触发渲染后用 get_app_status 轮询进度，完成后从 renderOutputPath 取成片路径。

安全模型

• 仅监听本机回环：服务绑定 127.0.0.1 并校验请求 Host 头（防 DNS rebinding），局域网与公网无法访问；
• Bearer token 鉴权：所有请求必须携带 Authorization: Bearer <token>，否则返回 401。token 首次启用时随机生成，经系统安全存储加密后保存在本机；设置页点「重新生成」后旧 token 立即失效；
• 渲染授权门禁不变：agent 触发的渲染与界面手动渲染走同一链路，免费版水印与 720p 限制同样生效；
• agent 无法通过 MCP 获取你在片语里配置的 LLM/TTS/ASR API key。

故障排查

• 连接被拒绝 / 端口不通：确认片语正在运行且已启用 MCP；端口被占用会自动顺延，以设置页状态行的实际地址为准。端口顺延后，片语下次启动会自动把已接入 agent 配置里的旧地址改写为新地址（重新生成过 Token 的除外）；仍连不上时在设置页对该 agent 重新「一键接入」；
• 401 未授权：token 错误或已作废（重新生成过）。从设置页重新复制接入配置；
• 工具返回「应用界面未就绪」：片语主窗口被关闭或正在重建，确认窗口打开后重试；
• request_render 返回「未设置输出目录」：先在「设置 → 默认输出目录」里配置；
• 新配置不生效：MCP 配置只在 agent 新会话启动时加载，写入配置后请重启 agent 或新建会话。