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

---

📦 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