Run the Mux MCP server locally on your machine. Use this guide when your AI client does not support remote MCP servers or when you must restrict the tools the server can run.
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: search_docs for searching Mux's documentation, and execute, which runs TypeScript written by your agent against the full Mux SDK, @mux/ts. When you run the server locally, execute runs code on your own machine in an isolated Deno sandbox whose network access is limited to the Mux hosts the SDK calls.
Before installing the Mux MCP Server, make sure you meet the following prerequisites:
@mux/mcp installs Deno for itself through an optional npm dependency. Where that can't install (a blocked binary download, npm install --omit=optional, or a platform without an npm build of Deno, such as Alpine), install Deno yourself and set DENO_PATH to the Deno executable.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) |
DENO_PATH | No | Path to a Deno 2.9 or newer executable, used when the bundled Deno can't install |
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-ts release and open it with Claude Desktop to install it. The bundle doesn't include Deno, so install Deno 2.9 or newer first, then set the bundle's DENO_PATH setting to the Deno executable (the output of which deno on macOS/Linux). Once that and your Mux credentials are configured, 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"
}
}
}
}VS Code reads MCP servers from an mcp.json file. To add the server to all of your workspaces, open your user configuration from the Command Palette with MCP: Open User Configuration. To add it to a single workspace, use .vscode/mcp.json in that workspace instead, and keep your credentials out of version control.
Add the server under "servers":
{
"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 mcp.json file, or from the Command Palette with MCP: List Servers.
By default the server exposes both tools and allows every SDK method. To change this, add flags after @mux/mcp@latest, either in your client's args array or at the end of the claude mcp add command.
| Flag | Values | Description |
|---|---|---|
--no-tools | code, docs | Disable a tool. --no-tools=code gives a docs-only server, and --no-tools=docs gives a code-only server |
--code-allow-http-gets | — | Allow methods that make HTTP GET requests, which makes the server read-only. This also blocks webhooks.unwrap, which makes no request; see below to allow it |
--code-allowed-methods | regex | Allow methods whose fully qualified name matches, such as video.assets.create |
--code-blocked-methods | regex | Block methods whose fully qualified name matches, even if an allow flag allows them |
Pass values with =, as in --no-tools=code. Repeat a flag to pass more than one value.
With no method flags, every method is allowed. Once you set either allow flag, only the methods they allow are available, and the two allow flags add together. --code-blocked-methods then removes methods from whatever is allowed. Every delete method has delete in its name, so delete is enough to block them all.
Read-only:
"args": ["-y", "@mux/mcp@latest", "--code-allow-http-gets"]Read-only, plus unwrapping webhooks:
"args": ["-y", "@mux/mcp@latest", "--code-allow-http-gets", "--code-allowed-methods=^webhooks.unwrap$"]Read-only, plus creating direct uploads:
"args": ["-y", "@mux/mcp@latest", "--code-allow-http-gets", "--code-allowed-methods=video.uploads.create"]Assets only, without deletes:
"args": ["-y", "@mux/mcp@latest", "--code-allowed-methods=^video.assets.", "--code-blocked-methods=delete"]Everything except deletes:
"args": ["-y", "@mux/mcp@latest", "--code-blocked-methods=delete"]Method flags keep an agent on task, but they aren't a security boundary: the server looks for method names in the code's text, so code that builds a method name at runtime gets past them. To guarantee the server can't change anything, give it an access token with only Read permissions.
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)Deno issues
A missing or too-old Deno is the most common local failure. The server still starts and search_docs still works, but every execute call fails with an error saying code execution needs Deno 2.9 or newer. To fix it:
--omit=optional, a blocked download, or a platform like Alpine), install Deno yourselfdeno --version and upgrade with deno upgrade if it's older than 2.9DENO_PATH in your client's env block to the absolute path of the Deno executable (the output of which deno). MCP clients often launch servers without your shell's PATH.mcpb bundle, set the bundle's DENO_PATH settingConnection 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: