ONOS

ONOS MCP Server provides programmatic access to an ONOS SDN controller, exposing network devices, topology, flows, analytics, and health information through a structured MCP API. This lets you build AI-assisted network management workflows, run analytics, and configure network behavior from automated agents.

How to use

You connect an MCP client to the ONOS MCP Server to perform operations such as querying network resources, retrieving analytics, managing applications, and creating or adjusting flow rules. Start the server using the provided standardized command, then configure your MCP client to point at the server endpoint and supply required credentials. Use the client to explore topology, devices, links, hosts, and performance metrics, or to push policy and flow configurations to the ONOS controller.

Below is a sample MCP configuration for running the ONOS MCP Server from your local environment. Use this to initialize your MCP client setup in your tooling so the client knows how to start and where to connect.

{
  "mcpServers": {
    "onos": {
      "command": "uv",
      "args": [
        "--directory",
        "parent_of_servers_repo/servers/src/onos-mcp-server",
        "run",
        "server.py"
      ],
      "env": {
        "ONOS_API_BASE": "http://localhost:8181/onos/v1",
        "ONOS_USERNAME": "onos",
        "ONOS_PASSWORD": "rocks"
      }
    }
  }
}

How to install

Prerequisites: Python 3.7+, a running ONOS controller, and dependencies for the MCP server. You will also need a runtime environment to execute the MCP client configuration (for example Claude Desktop or any MCP runner that supports the JSON configuration format). Ensure you have network access to the ONOS instance and that the ONOS REST API is reachable.

Step 1: Prepare the ONOS MCP Server runtime configuration by using the provided command and environment values in a client that supports MCP integrations.

Step 2: Run the MCP server entry as shown in the example configuration. This starts the local MCP process which connects to the ONOS API with the supplied credentials.

Configuration and security notes

Environment variables control how the MCP server authenticates to ONOS and where it exposes the API. Keep credentials secure and avoid embedding them in public scripts. Use separate credentials for development, staging, and production environments.

If you run into connectivity issues, verify that ONOS_API_BASE points to a reachable ONOS REST API endpoint and that ONOS_USERNAME and ONOS_PASSWORD are valid. Check ONOS cluster health and ensure that the ONOS REST API is enabled and accessible from the MCP server host.

Troubleshooting tips

• Confirm the MCP server process starts without errors
• Verify network reachability to the ONOS REST API
• Check logs for authentication failures or 4xx/5xx errors from ONOS
• Ensure required ONOS services and intents are properly configured in ONOS

Available tools

Network Resources

Access ONOS REST API endpoints for devices, links, hosts, topology, and system health

Analytics Tools

Provide network summary, network analytics, system health, application management, flow configuration, and path computation capabilities

Specialized Prompts

Network diagnostics, intent-based configuration, health analysis, QoS configuration, and performance optimization