SD-WAN MCP Server

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

![Python 3.10+](https://www.python.org/downloads/) ![FastMCP](https://github.com/jlowin/fastmcp) ![UV](https://github.com/astral-sh/uv) ![License](LICENSE)

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: ``bash export VMANAGE_URL=https://10.78.54.101 export VMANAGE_USER=admin export VMANAGE_PASS=your_password ``

2. Configuration File (config.yaml): ``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): ``json { "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: ``json { "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: ``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.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
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

Cisco SD-WAN MCP Server