sync. labs

sync. MCP 服务

将你的 AI Agent 连接到 sync.，即可为视频配音、将视频翻译并配制成其他语言、克隆声音，还可在聊天或编码会话中管理素材和项目。

sync. 在 https://mcp.sync.so/mcp 上托管此服务。你使用 sync. 账号登录，无需安装任何内容，也无需复制 API 密钥。每次将更改合并到此仓库的 main 分支时，都会部署到该服务。

连接你的 Agent

ChatGPT

打开 在 ChatGPT 中使用 sync.，并连接你的账号。在 ChatGPT 中，sync. Studio 也会在聊天内打开。

Claude（claude.ai 和 Claude Desktop）

1. 打开 Settings → Connectors，并选择 Add custom connector。
2. 将其命名为 sync.，并将 URL 设为 https://mcp.sync.so/mcp。
3. 点击 Connect，然后登录 sync。

Claude Code

claude mcp add --transport http sync https://mcp.sync.so/mcp

然后在 Claude Code 中运行 /mcp，选择 sync 并登录。添加 --scope user 即可在每个项目中使用。

Codex

codex mcp add sync --url https://mcp.sync.so/mcp
codex mcp login sync

Cursor

在项目的 .cursor/mcp.json 中添加配置；若要用于所有项目，则添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "sync": { "url": "https://mcp.sync.so/mcp" }
  }
}

Cursor 首次连接时会提示你登录 sync。

VS Code

添加到 .vscode/mcp.json：

{
  "servers": {
    "sync": { "type": "http", "url": "https://mcp.sync.so/mcp" }
  }
}

其他客户端

任何支持通过 Streamable HTTP 和 OAuth 连接远程 MCP 服务的客户端，都可以使用 https://mcp.sync.so/mcp。客户端会自行注册，你只需在浏览器中登录 sync.。

此服务已列入官方 MCP 注册表，名称为 io.github.synchronicity-labs/mcp-server，因此读取该注册表的客户端和目录都能找到并添加它。server.json 即为该服务的条目。

使用 API 密钥运行本地服务

对于不支持远程 MCP 的客户端，以及脚本和 CI，可通过 stdio 在本地运行服务，并使用 sync. API 密钥：

claude mcp add sync -e SYNC_API_KEY=your-api-key -- npx -y @sync.so/mcp-server@latest

或者添加到客户端的 JSON 配置中：

{
  "mcpServers": {
    "sync": {
      "command": "npx",
      "args": ["-y", "@sync.so/mcp-server@latest"],
      "env": { "SYNC_API_KEY": "your-api-key" }
    }
  }
}

如果没有设置 SYNC_API_KEY，服务会在首次运行时启动设备登录流程：访问它显示的 URL 并输入代码。令牌会缓存在 ~/.config/sync/mcp-credentials.json 中。

npm 版本会独立于托管部署发布，可能落后于托管部署，因此客户端支持时，建议优先使用托管服务。@latest 会让 npx 在客户端重启服务时获取最新版本；如果不加它，npx 可能会一直运行旧的缓存副本。

更新通知

本地服务启动时，会向 npm 注册表查询最新版本，每天最多查询一次（查询结果缓存在 ~/.config/sync/mcp-update-check.json 中）。该检查会在后台运行，限时两秒，绝不会延迟启动或工具调用；如果检查失败，则不会显示任何内容。如果有更新版本，服务的说明和会话中的第一个工具结果会告知 Agent，请求你使用 npx -y @sync.so/mcp-server@latest 重启，或切换到托管服务。

若要关闭此功能，请设置 SYNC_MCP_UPDATE_CHECK=off 或传入 --no-update-check。设置了 CI 时也会跳过检查；托管服务则从不检查。

可以询问什么

将如下提示词粘贴到你的 Agent 中。资产 ID 来自你的同步.library。 链接可以是公开媒体 URL，也可以是 YouTube、TikTok、Instagram 和 Facebook 视频。

询问	Agent 会执行的操作
"将视频资产 <video-asset-id> 与音频资产 <audio-asset-id> 进行唇形同步。"	使用已保存的资产调用 lipsync_create，然后等待结果
"将 https://example.com/talk.mp4 与 https://example.com/voiceover.wav 进行唇形同步。"	使用公开 URL 调用 lipsync_create
"将 https://www.youtube.com/watch?v=… 翻译成西班牙语。"	使用 assets_create 导入链接，报出费用，并在你确认后运行 dubbing_create
"让视频资产 <video-asset-id> 用平静的旁白音色说“感谢观看”。"	使用 voices_list 选择音色，报出脚本内容，然后使用 script 调用 lipsync_create
"我还剩多少积分？"	account_get-usage
"我上一次生成花了多少？"	在历史记录中查找，并读取 generations_get-costs

翻译、配音、语音预览和声音克隆都会先向你报价并获得确认，然后才会开始。

Agent 技能

这些工具（唇形同步、会说话的照片、配音、Edit Dialogue、营销活动、批处理、故障排除和 API）的分步工作流以 Agent 技能的形式提供，位于 synchronicity-labs/skills。使用 npx skills add synchronicity-labs/skills 即可在任何 Agent 中安装。ChatGPT 和 Codex 插件随附了该仓库固定提交版本中的技能；详见 docs/chatgpt-plugin.md。

工具

托管服务会向每个客户端提供一组精选工具：

区域	工具
唇形同步	lipsync_create、lipsync_create-timeline¹、generations_estimate-cost、generations_get、generations_list、generations_get-continuation、generations_get-costs、models_list
翻译和配音	dubbing_create、dubbing_get-options、translation-previews_estimate、translation-previews_create、translation-previews_get
语音和音色	speech-previews_create、speech-previews_get-options、speech-previews_get、voices_list、voices_clone
Edit Dialogue	dialogue_get-options、dialogue_upload-source、dialogue-transcriptions_create、dialogue-transcriptions_get、dialogue-previews_create、dialogue-previews_get、dialogue-videos_estimate、dialogue-videos_create
资产	assets_create、assets_create-upload-url、assets_get、assets_list、assets_count、assets_get-download-url、assets_update、assets_delete、assets_get-playback-metadata、audio-trims_get、audio-trims_create
项目	projects_create、projects_get、projects_list、projects_list-generations、projects_rename
批处理	batches_create²、batches_get²、batches_list²
账户	account_get-context、account_get-usage、organizations_list、organizations_select

¹ 不提供给 ChatGPT 应用，因为其内嵌 Studio 没有时间线。

² 目前尚未列入 ChatGPT 应用。批处理会运行 20 个或更多相互独立的生成任务（每批默认 500 个），例如将一条营销视频本地化为多种语言。如果账户套餐不包含批处理功能，API 会返回 402 和 requiredPlan、billingUrl，工具会转发这些信息。

启用了相应功能的组织还可以使用 scenes_detect（检测视频中的镜头切换）和 stems_separate（分离人声和背景音频）；这两项不适用于 ChatGPT 应用。它们在本地属于 lipsync 和 assets 工具集。

支持应用的客户端还可以使用内嵌 Studio 应用背后的工具： Studio 视图和草稿、上传小组件以及应用辅助工具。这些客户端的 MCP 握手名称会选择 ChatGPT 或 Codex 应用配置文件（openai-mcp、 openai-mcp (Codex)；参见 src/client-profile.ts）。其他客户端看不到这些工具，调用这些工具也会被拒绝。

本地工具集

本地 stdio 服务也可以为 OpenAPI 规范 中的其他每项公共 API 操作提供一个工具，共 65 多项。默认情况下，它会列出上面的托管工具集，但不包括其中的管理工具（assets_delete 和 voices_clone），另外还包括 jobs_get、jobs_wait 和 transcriptions_* 工具；这些工具中的说话人面部轨迹会为 lipsync_create-timeline 片段提供数据。

如需列出更多工具，请设置 SYNC_MCP_TOOLSETS，或使用逗号分隔的列表传入 --toolsets：

工具集	添加的工具
default	上述默认工具集；因此，default,admin 会在其中添加管理工具
lipsync	唇形同步、时间轴、Edit Dialogue、音频裁剪和批处理工具，以及原始的 generate_*、generations_* 和 dialogue-edits_*
dubbing	翻译和配音工具，以及批处理工具
assets	assets_*（删除操作除外）和上传工具
projects	projects_*（删除操作除外）和 projects_rename
transcription	transcriptions_*
voices	voices_*（克隆和删除操作除外）、语音预览和 tts_*
admin	所有删除操作（assets_delete、projects_delete、generations_delete、voices_delete）和 voices_clone
all	所有工具，与此选项推出前相同

每种选择都会包含作业、账户和生成记录读取工具（jobs_get、jobs_wait、generations_get、account_get-context、organizations_list、organizations_select 等）。指定工具集会替换默认工具集，而不是在其基础上添加。若要恢复所有工具：

claude mcp add sync -e SYNC_API_KEY=your-api-key -e SYNC_MCP_TOOLSETS=all -- npx -y @sync.so/mcp-server@latest

除非列出了所有工具，否则服务的说明会告知 Agent 已列出的工具集以及如何获取其余工具，因此它可以要求你用更广泛的工具集重新启动服务。托管服务会忽略此设置。

工具工作流介绍了多步骤工具和付费工具的行为。

工具名称遵循统一的 <noun>_<verb> 方案（lipsync_create、generations_get）。此前使用的名称（create-lipsync、generate_get-generation）在弃用期内仍然有效：通过这些名称发出的调用会运行相同的工具，并添加一行提示，注明新名称。工具名称中列出了完整的新旧名称对照表。

CLI 选项

Usage: sync-mcp [options]

Options:
  --api-key <key>     API key (or set SYNC_API_KEY env var)
  --base-url <url>    API base URL (default: https://api.sync.so)
  --transport <type>  stdio (default) or http
  --port <port>       HTTP port (default: 3002, only with --transport http)
  --no-spend-confirmation
                      Unattended automation: drop the cost-quote and confirm-before-paying
                      instructions (or set SYNC_MCP_SPEND_CONFIRMATION=off)
  --no-update-check   Skip the daily npm check for a newer version (or set
                      SYNC_MCP_UPDATE_CHECK=off; skipped when CI is set)
  --toolsets <list>   stdio only: comma-separated tools to list (or set SYNC_MCP_TOOLSETS):
                      default, lipsync, dubbing, assets, projects, transcription,
                      voices, admin or all (default: the hosted set without admin)
  -h, --help          Show this help message

无人值守自动化

默认情况下，这些工具会要求 Agent 报出付费操作的费用，并等待用户批准。当服务运行流水线或已获运营者支出许可的定时 Agent 时，请使用 --no-spend-confirmation（或 SYNC_MCP_SPEND_CONFIRMATION=off）启动。随后，Agent 可以直接创建作业，无需报出费用或征求同意；估算工具仍可使用。Agent 无法更改此设置。

作业工具接受 wait: true，可在服务端等待（每次调用最长约 50 秒；客户端发送 progressToken 时会提供进度通知）：generations_get、translation-previews_get、transcriptions_get，以及通过 assets_create 进行的社交媒体导入。在本地服务上，jobs_wait 和 jobs_get 可用一个输入 {kind, id, projectId?} 和一组统一的结果结构及状态，处理所有类型的作业（生成、转录、说话人分析、翻译预览、导入）；详见作业。

如果 API 提供此功能，feedback_send 可让 Agent 向 Sync 团队报告令人困惑的错误、错误结果和缺失的功能。

环境变量以及 HTTP 服务的会话、内存、上传和诊断限制，请参阅 HTTP 服务配置。

工作原理

1. 启动时，服务会从 {baseUrl}/api-json 获取公开的 OpenAPI 规范，并将每个操作转换为带有 Zod 输入架构的 MCP 工具。
2. 手写工具会在同一 API 上添加多步骤工作流，例如翻译和配音、编辑对话、语音预览和费用查询。
3. 每次工具调用都会向 sync. API 发送经过身份验证的请求，使用你的 OAuth 令牌（托管模式）或 API 密钥（本地模式）。

通过 stdio，新的公开 API 操作会在下次重启后成为工具。 托管服务仅公开允许列表中的工具，因此新增托管工具需随本仓库的某个版本一同发布。

编程式用法

你也可以将此服务用作库：

import { createSyncMcpServer, resolveConfig } from '@sync.so/mcp-server';

const config = resolveConfig({ apiKey: 'your-key' });
const server = await createSyncMcpServer(config);

开发

HTTPS 源测试会使用本地 openssl 命令创建有效期为一天的自签名测试身份。测试运行前会删除临时证书和密钥文件。

# Install dependencies
pnpm install

# Build
pnpm run build

# Run tests
pnpm test

# Lint
pnpm run lint

# Type check
pnpm run typecheck

# Script tests (monitor, smoke check, pre-commit size check)
pnpm run test:scripts

开发需要 Node 26 或更高版本（.nvmrc）；package.json 中的 devEngines 会在安装时强制执行此要求。pnpm install 会安装一个提交前钩子。该钩子会对暂存文件运行 Oxlint 和 Oxfmt，并阻止暂存源文件超过 5,000 个词元（20,000 字节）。对于已经超过该大小的文件，在有人拆分它们之前不会受到限制。

本地 HTTP 传输测试

要在本地测试 HTTP 传输（OAuth 流程）：

1. 将 .env.example 复制为 .env，并填写其中的值
2. 启动隧道以公开 localhost：

   ngrok http 3002
   

3. 使用 ngrok URL 更新 .env 中的 MCP_ISSUER_URL
4. 启动服务：

   source .env
   node dist/cli.js --transport http --base-url $SYNC_BASE_URL --port 3002
   

5. 验证是否正常运行：

   curl https://<ngrok-url>/health
   curl https://<ngrok-url>/.well-known/oauth-authorization-server
   

如果隔离的 Studio 登录需要使用同源 Web 代理，请将 SYNC_OAUTH_AUTHORIZATION_URL 设置为其 /api-proxy/v2/oauth/authorize URL，同时让 SYNC_BASE_URL 指向直接的隔离 API 监听器。只有浏览器导航会使用 Web 代理。注册、代码交换、刷新、撤销、用户信息和工具调用都使用直接 API，并保留现有的截止时间、PKCE 和机密客户端检查。此可选 URL 必须使用 HTTP(S)，且不得包含凭据、查询参数或片段。现有部署无需新增设置。

6. 在 Claude Web 中添加 https://<ngrok-url>/mcp 作为自定义连接器

了解更多

• 工具工作流 — 了解多步骤工具和付费工具的行为
• HTTP 服务配置 — 环境变量和运行时限制
• 维护者说明 — 托管兼容性、取消、OAuth 代理、上传和监控
• Claude 目录收录准备情况 — 审核清单和剩余的提交工作
• Sync 文档 — 完整的 API 参考和指南
• Sync API 参考 — 端点文档
• MCP 协议 — 了解模型上下文协议
• Sync 网站 — 注册并开始使用

许可证

MIT