Set up the Mux Model Context Protocol (MCP) Server locally to bring Mux's Video and Data platform capabilities directly to your AI tools.
If you just want to get started quickly, and to read more about how the server works, check out Using the Mux MCP Server. This guide covers running the Mux MCP Server locally on your machine and connecting it to various AI clients.
The Mux MCP (Model Context Protocol) Server brings Mux's Video and Data platform capabilities directly to your AI tools. Once installed, you can upload videos, manage live streams, analyze video performance, and access practically all of Mux's video infrastructure through natural language prompts in supported AI clients.
The server is published to npm as @mux/mcp and runs with npx — there's nothing to build or clone. Running locally (instead of using the hosted server at https://mcp.mux.com) is useful when your client doesn't support remote MCP servers, or when you want to restrict which tools and SDK methods the server is allowed to run.
The Mux MCP server uses the "Code Mode" tool scheme. Instead of exposing hundreds of individual endpoint tools, it exposes just two tools to your agent: a docs search tool and a code execution tool that writes TypeScript against the Mux Node SDK and runs it in an isolated sandbox. By default, code execution runs in Mux's hosted sandboxes; you can switch it to run on your own machine with --code-execution-mode=local (see Limiting tools and methods).
Before installing the Mux MCP Server, make sure you meet the following prerequisites:
MCP Access TokenThe two required environment variables are MUX_TOKEN_ID and MUX_TOKEN_SECRET. A few optional variables unlock additional functionality:
| Variable | Required | Used for |
|---|---|---|
MUX_TOKEN_ID | Yes | Access Token ID |
MUX_TOKEN_SECRET | Yes | Secret Key |
MUX_WEBHOOK_SECRET | No | Verifying and unwrapping webhook payloads |
MUX_SIGNING_KEY | No | JWT signing key ID for signed playback |
MUX_PRIVATE_KEY | No | JWT private key for signed playback |
MUX_AUTHORIZATION_TOKEN | No | Pre-built authorization token (alternative to token ID/secret) |
Important: Replace the placeholder values when adding to your AI client's config using the templates provided below:
your_access_token_id with your actual Mux Access Token IDyour_secret_key with your actual Mux Secret KeyNote: If you're using a tool that manages Node versions like Mise, you'll probably need to make sure you execute the npx commands found in the following examples from within that context. An example Mise command could look something like this:
mise x node@20 -- npx -y @mux/mcp@latest
Accordingly, the following examples would need to be changed similarly to below:
"command": "mise",
"args": ["x", "node@20", "--", "npx", "-y", "@mux/mcp@latest"],We support the Claude Desktop Extensions format, so you can download the mux.mcpb asset from the latest mux-node-sdk release and open it with Claude Desktop to install it. Once it's installed, configure the environment variables you need and you're good to go.
If you'd like to configure it manually, follow the next steps.
Follow Claude's instructions to locate your Claude Desktop configuration file on your machine.
macOS/Linux:
~/Library/Application\ Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonAdd this configuration block to your claude_desktop_config.json file:
{
"mcpServers": {
"mux": {
"command": "npx",
"args": ["-y", "@mux/mcp@latest"],
"env": {
"MUX_TOKEN_ID": "your_access_token_id",
"MUX_TOKEN_SECRET": "your_secret_key"
}
}
}
}Close and reopen Claude Desktop to load the new MCP server configuration.
You can add the server from your terminal with the claude mcp add command:
claude mcp add mux --env MUX_TOKEN_ID="your_access_token_id" MUX_TOKEN_SECRET="your_secret_key" -- npx -y @mux/mcp@latestFollow the paths below to locate your Cursor MCP configuration file. If the file does not exist, you can create it.
macOS/Linux:
~/.cursor/mcp.jsonWindows:
C:/Users/<username>/.cursor/mcp.json{
"mcpServers": {
"mux": {
"command": "npx",
"args": ["-y", "@mux/mcp@latest"],
"env": {
"MUX_TOKEN_ID": "your_access_token_id",
"MUX_TOKEN_SECRET": "your_secret_key"
}
}
}
}To add the server to all of your workspaces globally, add the server configuration to your settings.json file.
macOS:
~/Library/Application\ Support/Code/User/settings.jsonLinux:
~/.config/Code/User/settings.jsonWindows:
%APPDATA%\Code\User\settings.json{
"mcp": {
"servers": {
"mux": {
"command": "npx",
"args": ["-y", "@mux/mcp@latest"],
"env": {
"MUX_TOKEN_ID": "your_access_token_id",
"MUX_TOKEN_SECRET": "your_secret_key"
}
}
}
}
}In VS Code, make sure to click on the Start button for the MCP Server to start it. You can do this directly from the settings file, or from the Command Palette with MCP: List Servers.
By default the server exposes both the docs and code tools, runs code in Mux's hosted sandbox, and allows every SDK method. You can pass flags after @mux/mcp@latest in the args array to change this. The most useful options:
| Flag | Values | Description |
|---|---|---|
--tools | code, docs | Explicitly enable only these tools |
--no-tools | code, docs | Explicitly disable these tools |
--code-execution-mode | stainless-sandbox (default), local | Run code in the hosted sandbox or locally on the MCP server machine |
--code-allow-http-gets | — | Allow only methods that map to HTTP GET operations (effectively read-only) |
--code-allowed-methods | regex(es) | Allow only methods whose fully-qualified name matches (e.g. video.assets.*) |
--code-blocked-methods | regex(es) | Block methods whose fully-qualified name matches (e.g. .*\.delete) |
--docs-search-mode | stainless-api (default), local | Search hosted docs or a local in-memory index |
--transport | stdio (default), http | Run as a local stdio server or a remote Streamable HTTP server |
If none of the --code-allow-* / --code-blocked-methods flags are set, all methods are allowed. For example, to expose a read-only server that can only touch Mux Video assets:
"args": ["-y", "@mux/mcp@latest", "--code-allow-http-gets", "--code-allowed-methods=video.assets.*"],See the @mux/mcp README for the full list of flags.
Test that the Mux MCP Server is working by asking your AI client:
Give me the details for the most recently created Mux Video asset (using the Mux tool)
or
Using the Mux MCP, list the best performing countries for video streaming over the last month using Mux Data
If the installation was successful, your client will connect to the Mux API through the MCP server and return information about your video performance or assets.
Build issues
If you encounter errors when the server starts up:
npx is accessible in your PATH (npx -v)Connection issues
If your client can't connect to the MCP server:
Claude Desktop issues
If MCP features don't appear in Claude:
If you run into issues or have questions: