SD-WAN MCP Server

A FastMCP-based Model Context Protocol server for Cisco SD-WAN vManage automation

This package provides a modern FastMCP-based server for managing Cisco SD-WAN through vManage APIs, enabling AI assistants like Claude to automate SD-WAN operations through natural language.

✨ Features

🖥️ Device Management

• List all SD-WAN devices with status

• Get detailed device information and statistics

• Monitor interface statistics and health

• View control connections, BFD sessions, and OMP peers

• Track CPU, memory, and system status

📋 Template Management

• List and browse device/feature templates

• Create new feature and device templates

• Update existing templates with validation

• Deploy templates to single or multiple devices

• Preview template configurations before deployment

• Get template input requirements and variables

• Detach templates from devices

📊 Monitoring & Health

• Real-time alarms and events

• System-wide and per-device statistics

• Interface health and performance metrics

• Device health monitoring (CPU, memory, connectivity)

• BFD session status and control connections

• DPI (Deep Packet Inspection) statistics

• Application usage and threat reports

• Network-wide connection statistics

🔐 Policy Management

• Centralized and localized policy management

• Access control lists (ACLs) and prefix lists

• QoS maps and class maps

• Security policies and firewall rules

• SLA class definitions

• Route policies and redistribution

• Application-aware policies

• Site, VPN, and application lists

📦 Software Management

• List available software images

• Schedule software upgrades

• Track upgrade status and progress

• Automated pre-upgrade validation

📈 Reports & Analytics

• Comprehensive device reports (summary, detailed, health)

• Interface utilization reports

• Transport statistics and path analysis

• Security threat reports

• Application usage analytics

• Custom time-based reporting

🛡️ Safety & Validation

• Confirmation Required: All destructive operations require explicit confirmation

• Pre-execution Validation: Checks device connectivity, template compatibility, dependencies

• Rate Limiting: Prevents rapid-fire operations (configurable cooldowns)

• Auto-backup: Optional automatic backups before deployments/upgrades

• Operation Audit Log: Track all destructive operations with timestamps

• SSL Verification: Configurable for self-signed certificates

🚀 Performance & Architecture

• FastMCP Framework: Modern, efficient MCP implementation

• Async/Await: Non-blocking I/O for high performance

• Connection Pooling: Reusable HTTP connections to vManage

• Smart Caching: Optional caching for frequently accessed data

• UV Package Manager: Fast, reliable dependency management

Related MCP server: Cisco Meraki MCP Server

📦 Installation

Quick Start

# Clone the repository
git clone https://github.com/limtsi/sdwan_mcp.git
cd sdwan_mcp

# Install UV (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies and create .venv automatically
uv sync

# Configure credentials
cp config.yaml.example config.yaml
# Edit config.yaml with your vManage details

# Run the server
python sdwan_fastmcp.py

Detailed Installation

For comprehensive installation instructions, including troubleshooting and Claude Desktop integration, see:

📖 INSTALLATION_GUIDE.md

About UV

This project uses UV for fast, modern Python package management:

• uv sync automatically creates .venv and installs all dependencies from pyproject.toml

• 10-100x faster than pip for dependency resolution

• Automatic virtual environment management (no manual activation needed)

• PEP 621 compliant with pyproject.toml

Running the server:

• Simple: python sdwan_fastmcp.py (UV manages .venv automatically)

• Alternative: uv run python sdwan_fastmcp.py (explicit UV environment)

Both methods work equally well!

⚙️ Configuration

Configure vManage access using either:

1. Environment Variables:

export VMANAGE_URL=https://10.78.54.101
export VMANAGE_USER=admin
export VMANAGE_PASS=your_password

2. Configuration File (config.yaml):

vmanage:
  url: https://10.78.54.101
  username: admin
  password: your_password
  verify_ssl: false

🚀 Usage

1. Run as FastMCP server (recommended)

Simply run from the project directory:

python3 sdwan_fastmcp.py

Or use the virtual environment directly:

.venv/bin/python sdwan_fastmcp.py

Note: The .venv environment is managed by UV (via uv sync), but you run the server with standard Python commands.

2. Integrate with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

macOS/Linux (Recommended):

{
  "mcpServers": {
    "sdwan": {
      "command": "/Applications/MCP/sdwan/.venv/bin/python",
      "args": ["/Applications/MCP/sdwan/sdwan_fastmcp.py"],
      "env": {
        "VMANAGE_URL": "https://10.78.54.101",
        "VMANAGE_USER": "admin",
        "VMANAGE_PASS": "your_password"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "sdwan": {
      "command": "C:/path/to/sdwan/.venv/Scripts/python.exe",
      "args": ["C:/path/to/sdwan/sdwan_fastmcp.py"],
      "env": {
        "VMANAGE_URL": "https://10.78.54.101",
        "VMANAGE_USER": "admin",
        "VMANAGE_PASS": "your_password"
      }
    }
  }
}

Important: Use the direct path to .venv/bin/python (or .venv/Scripts/python.exe on Windows) for the most reliable configuration. Replace paths with your actual installation directory.

3. Use from Code

from sdwan_tools import SDWANTools

# Initialize tools
tools = SDWANTools()

# Get all devices
devices = await tools.handle_call("sdwan_get_devices", {})

# Deploy a template (with confirmation)
result = await tools.handle_call("sdwan_deploy_template", {
    "template_id": "template-123",
    "device_ids": ["device-456"],
    "confirm": True
})

🛠️ Available Tools

The server provides 50+ tools organized by category:

Device Management

• sdwan_get_devices - List all devices

• sdwan_get_device_status - Get device status

• sdwan_get_device_stats - Get device statistics

• sdwan_get_device_health - Comprehensive health metrics

• sdwan_get_device_bfd_sessions - BFD session info

• sdwan_get_device_control_connections - Control connections

• sdwan_get_device_omp_peers - OMP peer information

• sdwan_get_device_cpu_usage - CPU utilization

• sdwan_get_device_memory_usage - Memory utilization

• sdwan_get_device_system_status - Overall system status

Template Management

• sdwan_get_templates - List all templates

• sdwan_get_template_details - Template details

• sdwan_create_feature_template - Create feature template ⚠️

• sdwan_create_device_template - Create device template ⚠️

• sdwan_update_feature_template - Update feature template ⚠️

• sdwan_update_device_template - Update device template ⚠️

• sdwan_delete_feature_template - Delete feature template ⚠️

• sdwan_delete_device_template - Delete device template ⚠️

• sdwan_deploy_template - Deploy to devices ⚠️

• sdwan_detach_template - Detach from devices ⚠️

• sdwan_get_template_preview - Preview configuration

• sdwan_get_template_inputs - Get required inputs

Monitoring & Alarms

• sdwan_get_alarms - Get active alarms

• sdwan_get_events - Get system events

• sdwan_get_interface_stats - Interface statistics

• sdwan_get_network_stats - Network-wide statistics

• sdwan_get_dpi_statistics - DPI statistics

• sdwan_get_connection_statistics - Connection stats

Reports

• sdwan_get_device_report - Comprehensive device report

• sdwan_get_interface_report - Interface report

• sdwan_get_transport_report - Transport statistics

• sdwan_get_security_report - Security report

• sdwan_get_app_usage_report - Application usage

• sdwan_get_threat_report - Threat analysis

Software Management

• sdwan_get_software_images - List available images

• sdwan_schedule_upgrade - Schedule upgrade ⚠️

• sdwan_get_upgrade_status - Upgrade status

Policy Management

• sdwan_get_centralized_policies - List centralized policies

• sdwan_get_localized_policies - List localized policies

• sdwan_create_centralized_policy - Create policy ⚠️

• sdwan_update_centralized_policy - Update policy ⚠️

• sdwan_delete_centralized_policy - Delete policy ⚠️

• sdwan_activate_centralized_policy - Activate policy ⚠️

• sdwan_deactivate_centralized_policy - Deactivate policy ⚠️

• And 20+ more policy-related tools...

Generic API

• sdwan_api_call - Make custom vManage API calls

⚠️ = Requires confirmation (confirm: true)

📖 Example Usage

Get All Devices

{
  "name": "call_sdwan_tool",
  "arguments": {
    "tool_name": "sdwan_get_devices",
    "arguments": {}
  }
}

Deploy Template to Devices

{
  "name": "call_sdwan_tool",
  "arguments": {
    "tool_name": "sdwan_deploy_template",
    "arguments": {
      "template_id": "abc-123",
      "device_ids": ["device-1", "device-2"],
      "parameters": {
        "system_ip": "10.1.1.1",
        "hostname": "edge-router-01"
      },
      "confirm": true
    }
  }
}

Get Device Health

{
  "name": "call_sdwan_tool",
  "arguments": {
    "tool_name": "sdwan_get_device_health",
    "arguments": {
      "device_id": "device-123"
    }
  }
}

Schedule Software Upgrade

{
  "name": "call_sdwan_tool",
  "arguments": {
    "tool_name": "sdwan_schedule_upgrade",
    "arguments": {
      "upgrade_data": {
        "deviceIds": ["device-1", "device-2"],
        "imageId": "image-xyz",
        "reboot": true
      },
      "confirm": true
    }
  }
}

Natural Language with Claude

Once integrated with Claude Desktop, you can use natural language:

"Show me all SD-WAN devices that are currently down"

"Deploy the branch-template to all devices in the Seattle site"

"What are the current alarms in the network?"

"Schedule a software upgrade for all edge routers to version 20.9.2"

🛡️ Safety Features

Confirmation Requirements

All destructive operations require explicit confirmation:

# This will return a confirmation prompt
result = await tools.handle_call("sdwan_deploy_template", {
    "template_id": "abc-123",
    "device_ids": ["device-1"],
    "confirm": False  # or omit this field
})

# Response:
{
    "requires_confirmation": true,
    "operation": "deploy_template",
    "template_id": "abc-123",
    "device_count": 1,
    "message": "Set confirm=true to deploy template"
}

# Actually deploy
result = await tools.handle_call("sdwan_deploy_template", {
    "template_id": "abc-123",
    "device_ids": ["device-1"],
    "confirm": True  # Explicit confirmation
})

Pre-execution Validation

The server validates operations before execution:

• Device connectivity checks

• Template compatibility verification

• Dependency validation

• Maintenance window awareness (configurable)

Rate Limiting

Prevents rapid operations that could impact the network:

• Template deployments: 5 minutes between operations

• Software upgrades: 1 hour between operations

• Delete operations: 2 minutes between operations

Configure in config.yaml:

safety:
  rate_limits:
    template_deploy: 300  # seconds
    software_upgrade: 3600
    delete_operations: 120

Audit Logging

All destructive operations are logged:

2025-10-15 10:30:45 - sdwan_safety - INFO - Operation: sdwan_deploy_template
2025-10-15 10:30:45 - sdwan_safety - INFO - User: admin
2025-10-15 10:30:45 - sdwan_safety - INFO - Details: {"template_id": "abc-123", "device_ids": ["device-1"]}
2025-10-15 10:30:45 - sdwan_safety - INFO - Status: SUCCESS

🔧 Configuration Options

Basic Configuration

vmanage:
  url: https://10.78.54.101
  username: admin
  password: your_password
  verify_ssl: false
  timeout: 30
  max_retries: 3

Safety Configuration

safety:
  enabled: true
  require_confirmation: true
  validation:
    check_device_connectivity: true
    check_template_compatibility: true
    check_dependencies: true
  rate_limits:
    template_deploy: 300
    software_upgrade: 3600
  backup:
    auto_backup_before_deploy: true
    backup_retention_days: 30

Logging Configuration

logging:
  level: INFO  # DEBUG, INFO, WARNING, ERROR
  audit_operations: true
  audit_file: "sdwan_audit.log"

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository

2. Create your feature branch (git checkout -b feature/AmazingFeature)

3. Commit your changes (git commit -m 'Add some AmazingFeature')

4. Push to the branch (git push origin feature/AmazingFeature)

5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• FastMCP - Modern MCP framework

• UV - Fast Python package manager

• Cisco SD-WAN - SD-WAN solution

• Model Context Protocol - MCP specification

📞 Support

• Issues: GitHub Issues

• Documentation: Installation Guide

• MCP Docs: Model Context Protocol

🗺️ Roadmap

• Add support for SD-WAN fabric discovery

• Implement advanced policy templates

• Add real-time event streaming

• Support for multi-tenant vManage

• Enhanced error recovery and retry logic

• CLI tool for standalone operations

• Web UI for configuration and monitoring

Built with ❤️ for SD-WAN automation