MediaTrack MCP（NPX Only）

最短接入方式：使用 npx 直接启动，无需 clone 项目。

1. 获取凭证

打开分秒帧开放平台：https://open.mediatrack.cn/，联系在线客服咨询开通权限。
创建开放应用并获取：

• MEDIATRACK_APP_ID
• MEDIATRACK_APP_SECRET

OAuth 文档：https://open.mediatrack.cn/#/docs/api/global/oauth

2. 一行启动

MEDIATRACK_APP_ID="你的appid" \
MEDIATRACK_APP_SECRET="你的appsecret" \
MT_NOTIFY_SWITCH="on" \
MT_NOTIFY_WEBHOOK_URL="https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx" \
npx -y @mediatrack/mcp-server

说明：

• MEDIATRACK_APP_ID、MEDIATRACK_APP_SECRET 必填
• MT_NOTIFY_SWITCH 可选，默认 off
• MT_NOTIFY_WEBHOOK_URL 可选，配置后可接收工具调用通知

3. 主流客户端接入

统一配置原则：

• command: npx
• args: -y, @mediatrack/mcp-server
• env: MEDIATRACK_APP_ID, MEDIATRACK_APP_SECRET, MT_NOTIFY_SWITCH, MT_NOTIFY_WEBHOOK_URL

OpenCode

opencode mcp add mediatrack \
  --command "npx" \
  --args "-y" \
  --args "@mediatrack/mcp-server" \
  --env MEDIATRACK_APP_ID=你的appid \
  --env MEDIATRACK_APP_SECRET=你的appsecret \
  --env MT_NOTIFY_SWITCH=on \
  --env MT_NOTIFY_WEBHOOK_URL=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx

Claude Code

claude mcp add mediatrack \
  --command "npx" \
  --args "-y" \
  --args "@mediatrack/mcp-server" \
  --env MEDIATRACK_APP_ID=你的appid \
  --env MEDIATRACK_APP_SECRET=你的appsecret \
  --env MT_NOTIFY_SWITCH=on \
  --env MT_NOTIFY_WEBHOOK_URL=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx

Codex

在 ~/.codex/config.toml 中增加如下配置：

[mcp_servers.mediatrack]
command = "npx"
args = ["-y", "@mediatrack/mcp-server"]
startup_timeout_sec = 120

[mcp_servers.mediatrack.env]
MEDIATRACK_APP_ID = "你的appid"
MEDIATRACK_APP_SECRET = "你的appsecret"
MT_NOTIFY_SWITCH = "on"
MT_NOTIFY_WEBHOOK_URL = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"

Claude Desktop / Cursor / Cline / Continue / Windsurf

多数客户端都支持 mcpServers 配置，可用如下模板，字段名按客户端版本微调：

{
  "mcpServers": {
    "mediatrack": {
      "command": "npx",
      "args": ["-y", "@mediatrack/mcp-server"],
      "env": {
        "MEDIATRACK_APP_ID": "你的appid",
        "MEDIATRACK_APP_SECRET": "你的appsecret",
        "MT_NOTIFY_SWITCH": "on",
        "MT_NOTIFY_WEBHOOK_URL": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
      }
    }
  }
}

4. 快速验收

• 请列出我的所有项目
• 在项目“<项目名>”里搜索 <关键词>
• 获取资产 <资产ID> 的下载链接
• 把项目 <项目ID> 的 <文件夹名> 文件夹下载到 ~/Downloads
• 在项目 <项目ID> 中将资产 <原始资产ID> 与 <新资产ID> 创建为多版本文件
• 查看多版本壳 <多版本壳ID> 下的子文件及 rank 顺序
• 在项目 <项目ID> 中解除多版本子文件 <子文件ID>

5. 当前支持的 MCP 工具

• list_projects：获取项目列表
• search_assets：按关键词搜索资产
• list_folder_children：获取目录或多版本壳下的资产列表
• mget_assets：批量获取资产详情
• get_asset_detail：获取资产详情与媒体信息
• get_media_url：获取播放或下载地址
• reply_asset_comment：创建资产根批注或回复现有批注
• manage_folder：创建文件夹
• create_asset_version：创建多版本资产或向已有多版本壳添加最新版本
• remove_asset_version：从多版本资产中解除子文件
• upload_file：上传单文件
• upload_files：批量上传文件
• download_folder：递归下载文件夹内容
• call_openapi_endpoint：通用 OpenAPI 调用器

create_asset_version 的参数约定：

• projectId：项目 ID
• assetId：原始资产 ID 或已有多版本壳 ID
• nextAssetId：要加入的资产 ID；服务端会将其设为最新版本

remove_asset_version 的参数约定：

• projectId：项目 ID
• assetId：需要解除的多版本子文件 ID，必须满足 rank != 0

多版本壳内的子文件顺序由只读字段 rank 标识。使用 list_folder_children 传入多版本壳 ID 可查看子文件的 rank 与 versions；如需解除整个多版本，应逐个解除所有子文件。

多版本操作示例：

create_asset_version({ projectId: "项目ID", assetId: "原始资产ID", nextAssetId: "新资产ID" })
list_folder_children({ projectId: "项目ID", folderId: "多版本壳ID", page: 1 })
remove_asset_version({ projectId: "项目ID", assetId: "rank 不为 0 的子文件ID" })

reply_asset_comment 的参数约定：

• projectId：项目 ID
• assetId：资产 ID
• commentId：创建资产根批注时传 assetId；回复现有评论时传目标父评论 ID
• operateOrgMemberId：操作人组织成员 ID，可选；未传时会自动从 GET /projects/{project_id}/members 获取一个当前项目成员
• text：批注或回复文本
• begin / end：时间范围或位置范围
• timeEntryPoint / timeOutPoint：时间点信息

说明：

• 创建资产根批注时，commentId 传资产 ID
• 创建某条批注的回复时，commentId 传父批注 ID
• operateOrgMemberId 需要是当前项目成员，且具备对应操作权限
• 当仅传 begin 未传 end 时，服务端会以 begin 作为结束时间

6. 常见问题

• 鉴权失败：先确认 MEDIATRACK_APP_ID 和 MEDIATRACK_APP_SECRET 是否正确
• npx 拉起失败：确认 npm registry 可访问，并且当前环境能安装 @mediatrack/mcp-server
• 客户端里看不到工具：确认 MCP 配置已保存，并重启客户端
• 接口报错：查看返回里的 trace_id，联系平台支持排查