onos

The ONOS MCP Server exposes the ONOS SDN controller's REST API and management capabilities through a structured MCP interface. This enables AI assistants and automation tools to query network topology, devices, hosts, links, and analytics, as well as manage flow rules, intents, and ONOS applications. Core features include network resource access (devices, topology, flows, intents, applications), analytics such as network summary and performance metrics, and specialized prompts for diagnostics, intent-based configuration, health analysis, QoS setup, and performance optimization. With the provided API surface and prompts, you can programmatically monitor health, install or activate applications, configure flows and intents, and compute optimal paths between endpoints, all via the MCP abstraction.

To use the server, ensure the ONOS controller is running and accessible at the configured ONOS API base. The server exposes endpoints through the MCP interface that your AI agents can call to retrieve topology, push flow configurations, or run analytics queries. The included prompts guide common workflows such as diagnosing network issues, applying intent-based connectivity policies, and generating health or performance reports. Authentication is configured via environment variables, ensuring secure access to the ONOS REST API.

When launching, you can leverage the Claude Desktop setup example to integrate the MCP server into your environment. The server is designed to interact with ONOS through the REST API, so you can build automation around device discovery, topology exploration, and dynamic network reconfiguration using MCP calls.

Prerequisites

• Python 3.7+
• uv installed (for dependency management) https://docs.astral.sh/uv/getting-started/installation/#standalone-installer
• A running ONOS controller
• Internet access for Python package installation

Installation steps

1. Clone or obtain the ONOS MCP server repository (or ensure you have the server files).
2. Create and activate a Python virtual environment:

python3 -m venv venv
source venv/bin/activate

3. Install required Python packages (httpx and the MCP library) along with uv if not already installed:

pip install uv httpx mcp

4. Ensure ONOS credentials and API base are configured (you can set them via environment variables as shown in the README):

export ONOS_API_BASE=http://localhost:8181/onos/v1
export ONOS_USERNAME=onos
export ONOS_PASSWORD=rocks

5. Run the MCP server using uv from the appropriate directory:

uv --directory parent_of_servers_repo/servers/src/onos-mcp-server run server.py

6. Verify the server starts correctly and is reachable via the MCP interface at the configured endpoint.

Notes

• If your ONOS instance uses a non-default URL or credentials, update the ONOS_API_BASE, ONOS_USERNAME, and ONOS_PASSWORD variables accordingly.
• Ensure network access between the host running the MCP server and the ONOS controller on the required ports (REST API).

Tips and common issues:

• Environment variables must be exported in the shell where you run the server; the MCP client will read them for authentication against ONOS.
• If you encounter authentication errors, double-check ONOS_USERNAME and ONOS_PASSWORD and confirm ONOS is reachable at ONOS_API_BASE.
• When updating ONOS, ensure compatibility with httpx version requirements in your environment.
• Use the provided mcp configuration example to integrate into Claude Desktop or other MCP clients; adjust the directory and server path if your repository layout differs.
• Monitor ONOS system health metrics via the server analytics prompts to identify resource bottlenecks or controller health issues.