nmos-mcp

nmos-mcp

An MCP server for AMWA NMOS. It connects to an NMOS Registry, lets an agentquery everything on the network (IS-04) and — the headline feature — connectsenders to receivers to route media between devices (IS-05).

• IS-04 (Discovery & Registration) — read Nodes, Devices, Senders, Receivers,Flows, Sources and Subscriptions from the registry's Query API.
• IS-05 (Device Connection Management) — connect/disconnect, enable/disablesenders, inspect staged/active state, and bulk-route.
• Works against a plain-HTTP lab registry or an HTTPS deployment with IS-10OAuth2 bearer tokens.
• Finds the registry from NMOS_REGISTRY_URL, or auto-discovers it over mDNS(_nmos-query._tcp).

1. Install

cd nmos-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"          # or: uv pip install -e ".[dev]"

This creates the nmos-mcp console command inside .venv/bin/.

Note (this machine): the shell auto-activates another project's virtualenv, soplain python3 may be the wrong interpreter. If python3 -m venv fails, build thevenv with the real interpreter:env -i HOME="$HOME" PATH="/usr/bin:/bin" /opt/homebrew/bin/python3 -m venv .venvand use .venv/bin/python / .venv/bin/nmos-mcp directly.

2. Configure

Copy .env.example to .env and point it at your registry:

cp .env.example .env

NMOS_REGISTRY_URL=http://registry.example.local   # leave UNSET to auto-discover via mDNS
NMOS_QUERY_VERSION=v1.3
NMOS_CONNECTION_VERSION=v1.1
NMOS_USE_HTTPS=false
NMOS_VERIFY_TLS=true
# IS-10 auth (optional, for secured deployments):
# NMOS_AUTH_ENABLED=true
# NMOS_AUTH_TOKEN_URL=https://auth.local/oauth2/token
# NMOS_AUTH_CLIENT_ID=...
# NMOS_AUTH_CLIENT_SECRET=...

.env is git-ignored — internal hostnames (e.g. registry.example.local) andcredentials never get committed. .env.example is the only env file in git.

.env is read relative to the process working directory. When Claude Code launchesthe server the working directory may differ, so pass the registry URL via -ein the Claude Code registration below (that value is stored in your private Claudeconfig, not in the repo).

3. Start the server

The server speaks the MCP protocol over a transport — you normally don't run it byhand; an MCP client (Claude Code) launches it. To run it manually:

nmos-mcp            # stdio transport (what Claude Code / Claude Desktop use)
nmos-mcp --http     # streamable-HTTP transport

To poke at the tools interactively with the MCP Inspector:

mcp dev src/nmos_mcp/server.py

4. Add it to Claude Code

Register the server with the CLI (from anywhere). Use -e to inject the registry URLand -s local so it stays in your private config rather than the shared repo:

claude mcp add nmos \
  -s local \
  -e NMOS_REGISTRY_URL=http://registry.example.local \
  -- /ABSOLUTE/PATH/TO/nmos-mcp/.venv/bin/nmos-mcp

Verify it connected:

claude mcp get nmos       # Status: ✔ Connected
claude mcp list

Then in a Claude Code session just ask, e.g.:

"List the NMOS senders, then connect 'AES67 sender 4' to 'AES67 receiver 4'."

To update or remove it:

claude mcp remove nmos -s local          # then re-add with new flags

Scopes: -s local (default) keeps the server private to you for this project(stored in ~/.claude.json). -s user makes it available in all your projects.Avoid -s project (writes a committed .mcp.json) unless you deliberately want theregistry URL shared with the team via git.

Claude Desktop (alternative client)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "nmos": {
      "command": "/ABSOLUTE/PATH/TO/nmos-mcp/.venv/bin/nmos-mcp",
      "env": { "NMOS_REGISTRY_URL": "http://registry.example.local" }
    }
  }
}

Tools

IS-04 (query): registry_info, list_nodes, list_devices, list_senders,list_receivers, list_flows, list_sources, get_resource, query_resources.

IS-05 (connection): get_sender, get_receiver, get_sender_transport_file,connect_sender_to_receiver, disconnect_receiver, enable_sender,disable_sender, bulk_connect, stage_receiver, stage_sender.

How a connection is made

The Query API lives on the registry; the Connection API (IS-05) lives on eachNode. To wire a sender to a receiver the server:

1. Looks the receiver up in the registry and reads its device's controls array tofind the IS-05 endpoint (urn:x-nmos:control:sr-ctrl).
2. Fetches the sender's SDP transport file.
3. PATCHes the receiver's /staged with the sender id, master_enable: true,the transport file, and activation: { mode: activate_immediate }.
4. Reads back the receiver's /active state to confirm the route.

The connection endpoint version is taken from the device's advertised control href,so nodes exposing IS-05 v1.0 or v1.1 both work.

Test

pytest

Unit tests mock both the Registry Query API and a Node Connection API (via respx),covering the connect/disconnect PATCH bodies, endpoint resolution, config coercionand URL handling.

End-to-end against a real registry

Point NMOS_REGISTRY_URL at a live registry (or a local EasyNMOS stack:docker run -d --net=host rhastie/easy-nmos), then use mcp dev or Claude Code tolist_senders / list_receivers, run connect_sender_to_receiver, and confirm thereceiver's /active shows the sender's multicast group.

Scope & roadmap

Current: IS-04 read/query + IS-05 connection management. The module layout leavesroom to add IS-04 registration writes, IS-08 audio channel mapping, IS-07events/tally and IS-09 system parameters as additional tool groups.