片语 ← 返回首页

MCP 接入文档

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

片语内置一个 MCP（Model Context Protocol）服务器。开启后，本机的 AI agent（Kimi CLI、Claude Code 等）可以直接调用片语的宣传片制作能力：读取与修改故事板、查看画面（预览帧 / 素材抽帧 / 截图，以图片原生返回）、触发渲染、录屏截图——共 24 个工具，与片语内置 AI 助手完全同源。

给 AI agent 的速览（TL;DR）

片语在 http://127.0.0.1:17890/mcp 提供标准 MCP Streamable HTTP 端点（POST，无会话模式）。每个请求必须携带请求头 Authorization: Bearer <token>，token 由用户在片语「设置 → Agent 接入（MCP）」页面提供。端口以该页面状态行显示的实际值为准（被占用会自动顺延）。协议握手为标准 initialize → tools/list → tools/call；图片结果以 image content block（image/jpeg, base64）返回。按下方「方式三：手动配置」中的 JSON 片段写入你的 MCP 配置即可完成接入。

前置条件

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

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

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

完成后重启 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>" }

opencode

编辑 ~/.config/opencode/opencode.json（Windows：C:\Users\<用户名>\.config\opencode\opencode.json），在顶层 mcp 对象中加入：

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

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>"
      ]
    }
  }
}

工具清单（24 个）

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

工具说明
get_app_status获取应用状态：版本、授权、工程名、未保存更改、渲染进度/输出路径（触发渲染后轮询进度用）
get_templates获取全部可用视频模板清单（id、名称、描述、素材数量要求、默认时长）。搭故事板前必须先调用
get_storyboard获取当前故事板内容（各片段模板/文案/时长/转场/特效）
set_storyboard整体替换故事板。片段素材一律留空，由用户后续上传；校验失败返回错误，需修正后重试
update_segment修改某一个片段的部分字段（下标从 0 开始），未给出的字段保持原值
get_segment_media获取某段已上传素材清单（文件名/类型/时长/分辨率/裁剪区间/视口）
view_segment_frame抽取某段某视频在指定时间点的一帧画面（返回图片）
set_segment_trim裁剪某段某视频的可用区间（trimStart/trimEnd，秒）
set_segment_viewport设置某段某视频的取景视口：scale 缩放、offsetX/offsetY 平移
synthesize_narration对已填写旁白文案的段触发 TTS 语音合成（消耗 TTS 额度）
get_project_info获取项目整体信息：画幅、方向、总时长、片段数、背景音乐、旁白等
set_segment_captions设置某段的烧录字幕行（时间相对段起点）；传空数组清除
transcribe_segment_captions识别指定片段素材语音，自动生成烧录字幕（消耗 ASR 额度）
set_bgm_ducking背景音乐自动避让旁白（旁白响起时压低 BGM）
set_logo调整已上传 Logo 的位置/大小/透明度/显隐
request_render后台触发渲染视频，用 get_app_status 轮询进度
list_capture_sources列出可录制的屏幕与应用窗口（录屏/截屏前调用）
take_screenshot截取某个屏幕/窗口当前画面（返回图片），可保存为图片素材加入指定片段
start_screen_recording开始录制屏幕/窗口画面（与 stop_screen_recording 配对）
stop_screen_recording停止当前录制，保存为 webm 视频素材并加入指定片段
get_capture_status查询录屏状态：是否录制中、已录时长、源名称
view_media_frames一次抽取某素材多个时间点的画面（最多 4 帧，返回图片）
split_segment把某个片段在指定秒数处拆成两段（裁剪区间自动划分）
preview_storyboard_frame把当前故事板在指定时间点渲染成一帧成片画面（返回图片），导出前自检用

安全模型

注意：副作用操作自动执行

开启 MCP 即视为信任持有 token 的本机 agent——渲染、TTS/ASR 语音合成（消耗你配置的服务额度）、录屏/截屏等操作不再弹确认卡，直接执行。请只在你信任的 agent 配置里填写 token，不要分享接入配置。

故障排查