Mux MCP Server (Official)

什么是 Mux MCP Server (Official)？

Mux MCP 服务器是 Mux 官方提供的、把 AI 工具连接到 Mux Video 和 Data 平台的方式，让智能体可以通过自然语言提示词上传视频、管理直播并查询观看数据分析。

Mux 提供两种使用方式：位于 https://mcp.mux.com、支持 OAuth 登录的托管远程服务器，以及用访问令牌在本地运行的 npm 包 @mux/mcp。该包以 Apache-2.0 许可证开源，位于 muxinc/mux-ts 仓库（packages/mcp-server）。它没有为每个端点提供一个工具，而是采用 “Code Mode” 设计，只提供两个工具。

如何使用 Mux MCP Server (Official)？

你需要一个 Mux 账户。服务器能做什么，取决于你授权的 Mux 环境和访问令牌。

托管服务器（推荐）

添加一个 MCP 服务器（在 Claude 和 ChatGPT 中称为 “connector”），URL 填写 https://mcp.mux.com。支持 OAuth 的客户端会提示你登录 dashboard.mux.com 并选择一个环境，无需手动复制令牌。以 Claude Code 为例：

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

如果你的客户端不支持 OAuth，请在 Mux Dashboard 的 Settings → Access Tokens 中创建访问令牌，并以 Basic 凭据发送（对 TOKEN_ID:TOKEN_SECRET 做 base64 编码）：

{
  "mcpServers": {
    "mux": {
      "url": "https://mcp.mux.com",
      "headers": {
        "Authorization": "Basic <base64 of TOKEN_ID:TOKEN_SECRET>"
      }
    }
  }
}

不支持远程 MCP 的客户端可以使用下面的本地安装方式，或使用 mcp-remote。

本地安装

前置条件：Node.js、Mux 访问令牌 ID 和密钥，以及 Deno 2.9 或更新版本（@mux/mcp 会通过可选依赖自行安装 Deno；否则请设置 DENO_PATH）。必需的环境变量是 MUX_TOKEN_ID 和 MUX_TOKEN_SECRET。可选变量有 MUX_WEBHOOK_SECRET、MUX_SIGNING_KEY、MUX_PRIVATE_KEY（用于签名播放）和 MUX_AUTHORIZATION_TOKEN。

Claude Code

claude mcp add mux --env MUX_TOKEN_ID="your_access_token_id" MUX_TOKEN_SECRET="your_secret_key" -- npx -y @mux/mcp@latest

Claude Desktop

从 mux-ts 的最新 release 下载 mux.mcpb，用 Claude Desktop 打开即可安装（需先安装 Deno，并设置该扩展包的 DENO_PATH）。或者把以下内容添加到 claude_desktop_config.json 并重启：

{
  "mcpServers": {
    "mux": {
      "command": "npx",
      "args": ["-y", "@mux/mcp@latest"],
      "env": {
        "MUX_TOKEN_ID": "your_access_token_id",
        "MUX_TOKEN_SECRET": "your_secret_key"
      }
    }
  }
}

Cursor

把同样的 mcpServers 配置块添加到 ~/.cursor/mcp.json（如果文件不存在请先创建）。

VS Code

打开 MCP: Open User Configuration（或在单个工作区使用 .vscode/mcp.json），在 "servers" 下添加服务器，使用相同的 command、args 和 env，然后点击 Start。

可以用这句提示词测试：“Give me the details for the most recently created Mux Video asset (using the Mux tool)”。

Mux MCP Server (Official) 的主要功能

• 完整覆盖 Mux SDK：Mux Video（资源、直传上传、playback ID、轨道、直播）、Mux Data（指标、维度、实时数据、观看记录、导出）、Mux Robots、签名密钥和 webhooks。
• Code Mode：智能体基于 @mux/ts SDK 编写 TypeScript，一次调用即可完成多步骤任务，同时保持较小的上下文窗口占用。
• 沙箱执行：托管服务器的每次调用都在一个全新的、隔离的 Mux 自有沙箱中运行；本地调用在只能访问 Mux API 主机的 Deno 沙箱中运行。
• 托管服务器支持 OAuth：登录并选择环境即可，配置文件中不需要任何密钥。
• 方法允许/阻止列表：本地运行时可以用参数把服务器设为只读，或限制为特定的 SDK 方法。
• 官方且开源：由 Mux 以 Apache-2.0 许可证发布。

Mux MCP Server (Official) 工具

服务器提供两个工具：

• search_docs 查询 Mux API 和 SDK 的文档。
• execute 运行智能体编写的、基于完整 Mux SDK 的 TypeScript 代码，并返回代码返回或打印的任何内容。

在本地运行时，可以在 @mux/mcp@latest 后添加参数来收窄范围：--no-tools=code（仅文档）或 --no-tools=docs、--code-allow-http-gets（只读）、--code-allowed-methods=<regex> 和 --code-blocked-methods=<regex>（例如用 --code-blocked-methods=delete 阻止所有删除方法）。

Mux MCP Server (Official) 的使用场景

• 管理视频：“列出我所有的视频资源及其当前状态。”
• 获取播放链接：“给我 Mux 账户中最近上传的视频的播放 URL。”
• 增加无障碍支持：“为资源 ID ASSET_ID 生成字幕轨道。”
• 使用 Mux Robots：“运行一个 Robots 任务，为这个资源生成章节”，或者总结视频内容并建议标签。
• 分析表现：“上个月哪个国家的视频播放表现最好？” 或 “我的账户中最常见的视频错误是什么？”
• 构建功能：“创建一个可以把视频上传到 Mux 的网页。”

Mux MCP Server (Official) 与替代方案对比

• 托管 vs 本地：托管服务器配置最快（OAuth、无需安装、由 Mux 运行沙箱）。当客户端不支持远程 MCP，或你希望用参数限制工具和 SDK 方法时，在本地运行 @mux/mcp。
• MCP vs 直接使用 SDK：对于固定的生产工作流，请在你自己的代码中调用 @mux/ts 或 Mux API。MCP 服务器适合由智能体驱动的临时任务和探索。
• 无关的 “mux” 项目：搜索结果中还会出现 McpMux、mcp-mux 等 MCP 多路复用器。它们用于聚合 MCP 服务器，与 Mux Video 毫无关系。

Mux MCP Server (Official) 常见问题排查

• execute 报 Deno 错误：缺少 Deno 或版本过旧是本地最常见的故障（search_docs 仍可使用）。安装 Deno 2.9+，用 deno --version 检查版本，并在客户端的 env 中把 DENO_PATH 设为 which deno 的输出。
• 服务器无法启动：确认已安装受支持的 Node.js 版本，并且可以在 PATH 中运行 npx -v。使用 Mise 时需要包装命令，例如 mise x node@20 -- npx -y @mux/mcp@latest。
• 无法连接或未授权：核对令牌 ID 和密钥，去掉多余的空格，并确认令牌在该环境中拥有所需权限。
• Claude Desktop 中看不到工具：更新到最新版本，检查 JSON 是否有效，并完全重启应用。