Transcodely

Transcodely MCP 服务

面向 AI Agent 的视频处理流水线，基于 Model Context Protocol 构建——绝不会删除你的任何内容。

将视频 URL 交给你的 Agent，它就会返回一个可播放的链接：视频会被转码为 ABR 码率阶梯、托管，并可按需添加字幕。之后，让它读取实际生成的内容、费用，以及上传未能创建任务的原因。没有删除、取消或密钥材料。只需点击一次 OAuth 即可连接——无需创建或粘贴 API 密钥。

• 服务 URL（可流式传输的 HTTP）： https://mcp.transcodely.com/mcp
• 产品页面： https://www.transcodely.com/mcp
• 连接指南： https://www.transcodely.com/docs/guides/mcp
• 注册表标识符： com.transcodely/mcp

这是托管服务的官方主页：包含连接说明、工具列表和注册表清单。服务本身是托管服务——无需安装或运行任何内容。

连接

Claude Code

claude mcp add --transport http transcodely https://mcp.transcodely.com/mcp

然后在 Claude Code 中运行 /mcp 并选择 Authenticate——浏览器会打开，批准后即可使用这些工具。还没有 Transcodely 账户？授权过程中会为你创建一个。

claude.ai / Claude 桌面应用 — Settings → Connectors → Add custom connector → https://mcp.transcodely.com/mcp。

Cursor — 添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "transcodely": { "type": "http", "url": "https://mcp.transcodely.com/mcp" }
  }
}

任何支持通过可流式传输的 HTTP 连接远程 MCP 服务的其他客户端也都可以使用相同方式连接。对于无头环境（CI、服务端 Agent），请改为将 Transcodely API 密钥作为 bearer token 附加——请参阅连接指南。

工具（19 个）

共有 19 个工具：12 个仅读取，5 个会创建内容——其中 4 个会启动计费任务，另有 1 个可免费保存预设；还有 2 个会覆盖某项设置，但只影响之后创建的任务。此处列出的工具均不会删除、取消、移除或轮换任何内容。

工具	效果	功能说明
create_job	创建任务 · 计费	创建转码任务。
create_preset	创建 · 免费	为此应用创建自定义编码预设：一组命名且可重复使用的编码设置，create_job 可通过 slug 引用它。
create_video_from_url	创建任务 · 计费	获取远程 https:// 视频并在一次调用中托管它——当你想要“转码并托管此视频，然后给我一个链接”时，就使用此工具。
generate_captions	创建任务 · 计费	根据已托管视频的 ID（vid_...）生成 AI 字幕。
generate_insights	创建任务 · 计费	根据已托管视频 ID（vid_...）对应的现有 AI 字幕生成 AI 洞察（标题建议、摘要、要点、章节、问题、关键术语、精彩引述、主题）；不会重新转录。
get_ingest_rule	读取	按 ID（ing_...）获取一条摄取规则：其来源、启用状态、筛选条件、提交的任务，以及事件数和任务数。
get_job_status	读取	按 ID（job_...）获取转码任务的简明状态快照：整体状态和进度、任何错误代码／消息，以及各输出的状态／进度和错误。
get_output_report	读取	获取某个任务输出（job_... 加 out_...）的完整测量报告：根据写入的文件测得的实际文件属性，以及将其与任务要求对比后的判定结果。
get_pricing	读取	返回此应用支付的欧元价格：所有计费项目（按编解码器计费的编码、分辨率、质量和功能乘数、字幕、洞察和处理费用、托管存储和交付），以及每项的费率和计量单位；若此账户有自定义费率，则标记 custom: true，并列出对应的公开标价。
get_seo_markup	读取	获取可直接粘贴的 SEO 标记，用于在你自己的网页上通过 watch_url 展示已托管的视频（vid_...，状态为 ready、public 或 unlisted）：schema.org VideoObject JSON-LD（视频有洞察时包含章节关键时刻）、视频站点地图条目，以及包含摘要、章节链接和完整转录文本的转义 HTML 片段。watch_url 只会嵌入输出，不会被获取。
get_transcript	读取	获取已托管视频（vid_...）的 AI 字幕转录文本，格式可为 txt（纯文本，默认）、md（带时间戳链接的 Markdown）或 json（包含带时间信息的段落、句子和单词）。
get_usage	读取	返回某个计费月份的托管用量和费用：编码视频数、编码分钟数、平均存储量、出口流量、请求数，以及以欧元计的逐项费用和总费用。
get_video	读取	按 ID（vid_...）获取已托管视频：状态、可见性、标题、时长、海报图像、已编码版本（分辨率、编解码器、比特率、尺寸），以及状态为 "ready" 后可用的播放信息块。
list_ingest_events	读取	按时间倒序列出此应用的摄取规则收到的存储交付，并显示每项的处理结果：存储桶和对象键、结果（received、matched、created、skipped 或 failed）、跳过或失败的原因，以及创建任务时对应的任务 ID。
list_ingest_rules	读取	列出此应用的摄取规则：这些常驻指令会将存储来源中新增的对象转换为转码任务。
list_jobs	读取	按时间倒序列出已通过身份验证的应用的转码任务。
list_presets	读取	列出此应用可用的编码预设：平台提供的只读预设和应用自有的自定义预设。
set_spend_limit	覆盖设置	设置或清除此应用每月的转码支出上限，单位为欧元。
update_preset	覆盖设置	按 ID（pst_...）更新自定义预设的设置。

由 tools.json 生成，使用 npm run readme:gen — 请勿手动编辑。只读：12。写入：7。计费：4。

该接口无法执行的操作

承诺范围狭窄且明确，并且会经过检查，而非仅仅声明：test/vendored.mjs 会在每次 CI 运行时从 tools.json 重新推导这一承诺；如果未来版本添加了名称以 delete、cancel、remove、purge、rotate 或 destroy 开头的工具，检查就会失败。

• 不会删除或取消任何内容。 没有工具可以移除视频、任务、输出、预设或规则，也没有工具可以停止已排队或正在运行的工作。Agent 如果在任务中途决定“清理”，也没有工具可用。
• 不会读取密钥或机密材料。 没有用于 API 密钥的工具，而且摄取工具会刻意隐去 REST API 会显示的密钥前缀和末四位提示：规则的入站密钥仅在创建时显示一次，此后此服务绝不会显示。工具结果会进入 Agent 的对话记录，因此任何不应出现在对话记录中的内容都不会出现在该接口上。
• 不会访问你的组织。 成员、套餐、发票、团队设置和管理界面都没有对应工具。
• 这对会覆盖值的工具只会影响后续操作。 update_preset 和 set_spend_limit 带有 destructiveHint: true，在协议中表示“替换一个值”，而非“进行增量修改”——并不表示会删除任何内容。预设会在创建任务时读取并展开，因此编辑预设不会影响已存在的任务；降低支出限额会阻止下一个任务，但绝不会停止正在进行的任务。

谁可以更改支出限额

set_spend_limit 是唯一自带授权规则的工具，因为它是唯一会调整资金政策的工具。

• 它要求用户是组织所有者或管理员，并通过浏览器 OAuth 流程登录。这与 REST API 执行的成员资格检查相同，此外还多了一条 REST API 没有的规则。
• API 密钥会话会被直接拒绝——包括下方使用 ak_… 进行身份验证的 stdio 桥接。拒绝原因会以文字明确说明，而不是笼统地报出权限错误。在这一点上，此接口有意比 REST 更严格：通过 REST，密钥可以管理其所属应用的限额。
• 它会读取并返回限额，而不是原样回显传入的值：即使设置的限额高于套餐或平台上限，也会成功保存，但不会产生任何影响，因为较低的上限仍然有效。结果会包含变更前后的有效限额，以及该限额所依据的层级。

身份验证与防护措施

• 通过浏览器授权使用 OAuth 2.1 和 PKCE；此服务实现了 RFC 9728 受保护资源元数据和 RFC 8707 资源指示器。
• 每次工具调用都限定在一个 Transcodely 应用内，应用由会话确定，而不是由工具参数指定。Agent 无法通过传入其他 ID 来扩大自身范围：属于其他应用的任务、视频、预设或规则会显示为未找到，而不是权限错误，从而避免确认它们是否存在。连接到 https://mcp.transcodely.com/mcp/app_… 可固定到特定应用；不带应用 ID 的基础 URL 会解析到你组织中启用时间最早的应用。
• 在其他应用的 URL 上提供的 ak_… 密钥会被直接拒绝。
• 每次调用都会写入与对应 REST 调用相同的审计记录。
• 连接 MCP 服务无需付费。四个工具会启动计费工作——create_job、create_video_from_url、generate_captions 和 generate_insights——费用按Transcodely 的常规费率收取。其他所有工具均可免费调用，包括会写入数据的工具：保存预设或设置支出限额都不收费。

试用

1. “转码并托管这段视频，然后给我一个链接：https://www.transcodely.com/videos/bbb-30s.mp4”
2. “为那段视频生成英文字幕。”
3. “我上一个任务的状态是什么？”
4. “那个 1080p 输出实际是 1080p h264 吗？给我看看测量报告。”
5. “我向自己的存储桶上传了文件，却没有生成任务——发生了什么？”
6. “我这个月在视频上花了多少钱？哪天花得最多？”

在本地运行（stdio 桥接）

支持远程连接的客户端应直接连接上方托管的端点——这是单击式 OAuth 路径。对于仅支持 stdio 的客户端、沙盒和无头用法，此仓库也可作为可运行的桥接程序，通过 stdio 提供相同的工具，并将调用转发到托管服务：

# with an API key (create one in the Transcodely dashboard):
TRANSCODELY_API_KEY=ak_... npx github:transcodely/mcp

# or via Docker:
docker build -t transcodely-mcp .
docker run -i --rm -e TRANSCODELY_API_KEY=ak_... transcodely-mcp

未设置 TRANSCODELY_API_KEY 时，桥接程序仍会启动并响应自省请求（initialize、tools/list）；工具调用会返回错误，并指向两种身份验证路径。set_spend_limit 会列出，但始终会通过此路径拒绝——参见上方规则。

如何确保 tools.json 准确无误

tools.json 是生成的，而非手动编写的：它是 Transcodely API 自带导出命令 go run ./cmd/mcp --dump-tools 的逐字节精确标准输出，该命令在检出 api-pin.json 中固定的版本后运行。上方的 README 表格又是根据它生成的。以下两项检查可确保这条链路：

检查	命令	运行时机
内置内容一致性——计数、注释、“不会删除任何内容”的承诺、清单版本，以及 README 列出每个工具	node test/vendored.mjs	每次推送和 PR
桥接程序提供的内容与内置内容完全一致，且无密钥调用会提供指引	node test/introspect.mjs	每次推送和 PR
从 tools.json 重新生成 README 表格	node scripts/gen-readme.mjs --check	每次推送和 PR
tools.json 与固定的 api 版本逐字节精确一致	npm run tools:check	有可用令牌时——见下文

要提交工具集变更：

# 1. point api-pin.json's "ref" at the release you are vendoring
# 2. read a DETACHED WORKTREE at that tag — never the shared api checkout,
#    which other sessions commit to and which sits on master
git -C ~/git/transcodely/api worktree add --detach /tmp/api-pin v5.X.0
TRANSCODELY_API_PATH=/tmp/api-pin npm run tools:sync
npm run readme:gen
git -C ~/git/transcodely/api worktree remove /tmp/api-pin
# 3. bump the version in server.json + package.json, in the same commit
npm test

也可以完全跳过第 2 步：设置 API_REPO_TOKEN 且不设置 TRANSCODELY_API_PATH 时，脚本会自行克隆固定的标签。这是唯一会验证固定版本的模式，因此建议优先使用。

必须如实说明的限制：transcodely/api 是私有仓库，因此一致性任务需要在 API_REPO_TOKEN 中提供读取令牌，且无法在来自 fork 的拉取请求上运行。缺少令牌时，脚本会以 78 退出，任务会报告未启用，而不是通过——它绝不会声称通过了实际未检查的一致性验证。上述始终运行的检查仍能发现这里实际发生过的偏差：导出内容已变更，而 README、清单和桥接程序仍保留旧数据。

清单

server.json 是发布到官方 MCP 注册表的清单。重新发布时必须递增其 version，才能使变更生效——注册表会提供上次发布版本的说明，因此只修改说明而不更改版本不会生效。