ONOS MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
ONOS MCP Server
A standalone Model Context Protocol server for ONOS-managed networks, plus a JSON-driven Mininet topology launcher. The server discovers hosts, switches, and links from ONOS at call time, so it is not tied to a fixed topology.

It supports:
stdio for desktop MCP clients;
Streamable HTTP for browser clients such as the llama.cpp Web UI;
host-to-host intents, connectivity checks, and direct link up/down.
The repository contains both the MCP server and the topology launcher.
Quick start
uv sync
cp .env.example .env
# edit .env: ONOS_URL, credentials, and optional ONOS_CONTROL_URL
uv run main.py --selftestFor a browser client, set ONOS_HTTP=1 in .env, for a stdio client, set ONOS_HTTP=0 and run:
uv run main.pyThe MCP endpoint is http://127.0.0.1:8000/mcp; health is at
http://127.0.0.1:8000/health.
curl http://127.0.0.1:8000/healthWithout ONOS_HTTP=1 or --http, the server waits for JSON-RPC on stdin and does not open a port.
Related MCP server: otg-mcp
Requirements
Linux or macOS with
uv.Python 3.12+ managed by
uv.ONOS northbound REST, usually
http://<onos-host>:8181.Optional control API:
The topology control API, usually
http://<topology-host>:9090.Mininet on the machine running
topology/start_topo.py.
The MCP server does not start ONOS or the topology. If you only need discovery and host intents, the control API is optional.
Tools
Tool | Purpose |
| Hosts, switches, links, aliases, intents, flows, and control health. Call first. |
| Hosts discovered by ONOS. |
| Active host-to-host intents, optionally including withdrawn ones. |
| Priority-100 intent flows grouped by switch. |
| Create a host-to-host intent and wait for |
| Remove the intent matching two hosts. |
| Connect hosts with an intent, or bring a switch/host-switch link up. |
| Remove a host intent, or bring a switch/host-switch link down. |
| Ping one host from another through the control API. |
| Bring any direct link up or down through the control API. |
Resources use the onos:// scheme. Additional reference material is in MCP_SERVER.md.
Host and switch names
Names are resolved against live ONOS inventory:
hosts become
h<last IPv4 octet>when unique, for exampleh5for10.20.0.5;switches become
s<hex datapath number>when unique, for examples5forof:0000000000000005;IPs, MACs, full ONOS host IDs, and full device IDs also work.
For different names, use aliases:
uv run main.py \
--host-alias h5=10.20.0.5 \
--switch-alias edge=of:0000000000000005Or set ONOS_HOST_ALIASES and ONOS_SWITCH_ALIASES in .env.
ONOS and the control API
The server uses two independent endpoints, both interpreted from the machine where the MCP server runs:
Setting | Endpoint | Needed for |
| ONOS REST, usually port 8181 | Discovery, intents, flows |
| Mininet control API, usually port 9090 | Pings, link changes, switch/host-switch connect |
The MCP server does not SSH into the VM. For a ping or link change it sends JSON to the control API, which runs the operation inside Mininet.
If ONOS runs in a VM and the MCP server runs on the host, forward ports 8181 and 9090 and bind the control API to 0.0.0.0. If the MCP server runs inside the VM, use 127.0.0.1 for both.
Without ONOS_CONTROL_URL, these fail with an explanatory error:
check_connectivity, set_link, and switch/host-switch connect_nodes/disconnect_nodes. Host-to-host intents still work.
Mininet topology launcher
topology/ is separate from the MCP package. It starts a topology from JSON, connects its switches to ONOS, and optionally starts the control API.
cd topology
sudo python3 start_topo.py \
--topology example.json \
--controller-ip 127.0.0.1 \
--controller-port 6653 \
--control-host 0.0.0.0 \
--control-port 9090Use --clean to run mn -c first, --hold N to run without the interactive CLI, and --control-port 0 to disable the control API. Stop with Ctrl-C so Mininet can clean its interfaces.
See topology/README.md for the JSON schema and topology/example.json for a complete example.
Configuration
Variable | Default | Meaning |
|
| ONOS northbound URL |
|
| ONOS REST username |
|
| ONOS REST password |
|
| Intent application ID |
| empty | Mininet control API URL; empty disables it |
| empty | Host aliases, |
| empty | Switch aliases, |
| off | Set to |
|
| HTTP bind address |
|
| HTTP port |
|
| Streamable HTTP path |
|
| Comma-separated allowed CORS origins |
| empty | Explicit env file; |
.env is loaded from the current directory or project root. Existing shell variables take precedence. Use --env-file PATH or ONOS_ENV_FILE for a different file. Equivalent flags include --onos-url, --onos-user, --onos-password, --app-id, --control-url, --http, --http-host, --http-port, --http-path, and --cors-origin.
MCP client configuration
Stdio:
{
"mcpServers": {
"onos": {
"command": "uv",
"args": ["run", "--directory", "<project-root>", "main.py"],
"env": {
"ONOS_URL": "http://<onos-host>:8181",
"ONOS_USER": "onos",
"ONOS_PASSWORD": "rocks",
"ONOS_APP_ID": "org.onosproject.cli",
"ONOS_CONTROL_URL": "http://<topology-host>:9090"
}
}
}
}HTTP browser client: start the server with ONOS_HTTP=1 or --http, then add the Streamable HTTP URL:
http://<mcp-server-host>:8000/mcpUse /mcp, not /sse. If the browser runs on another machine, bind --http-host 0.0.0.0 and allow the port through the firewall.
Testing
uv run python -m unittest -v \
tests.test_topology_config \
tests.test_topology_control \
tests.test_http_transport \
tests.test_mcp_server \
tests.test_intent_toolsExpected: 39 tests, with the live ONOS test skipped unless ONOS_LIVE=1.
ONOS_LIVE=1 uv run python -m unittest -v tests.test_intent_toolsTroubleshooting
uv run main.pyprints nothing: it is in stdio mode, waiting on stdin. SetONOS_HTTP=1or use--http.Browser
NetworkErrororDisallowed CORS origin: setONOS_CORS_ORIGINS=*or the exact Web UI origin, then restart the server.No hosts: ONOS has not discovered them yet. Generate traffic and call
get_network_contextagain.Control disabled: set
ONOS_CONTROL_URLand restart the MCP server.Control API connection refused: confirm the topology is running and the port is reachable from the MCP server.
Security
The HTTP MCP endpoint has no authentication. Bind
127.0.0.1unless a remote client needs it; otherwise use a firewall or a TLS reverse proxy.The control API also has no authentication. Do not expose it to an untrusted network.
Keep
.envprivate; it is ignored by git.Change the default ONOS credentials if your controller uses different ones.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Streamable HTTP MCP gateway for NV oOS fleets — one API key, namespaced tools, quotas and policy.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Manage Nife.io cloud apps, sites, secrets and Git integrations from MCP clients.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that provides programmatic access to ONOS SDN controller's network management capabilities, enabling device control, topology management, and analytics through ONOS's REST API.6GPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables interaction with Open Traffic Generators (OTG) through a standardized API, allowing configuration, traffic control, and metrics collection via MCP.15Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables network configuration, connectivity testing, and routing management for ContainerLab Linux containers through an MCP interface.3-
- AlicenseAqualityBmaintenanceProvides MCP tools for governed multi-vendor network device operations, including configuration management (backup, diff, merge, replace, rollback) and read-only queries (facts, interfaces, BGP, LLDP, ARP) via NAPALM, with optional NetBox source-of-truth integration.33MIT