# SD-WAN MCP Server

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

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/FastMCP-enabled-green.svg)](https://github.com/jlowin/fastmcp)
[![UV](https://img.shields.io/badge/UV-package%20manager-orange.svg)](https://github.com/astral-sh/uv)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](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

```bash
# 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](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:

```bash
python3 sdwan_fastmcp.py
```

Or use the virtual environment directly:

```bash
.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

```python
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

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

### Deploy Template to Devices

```json
{
  "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

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

### Schedule Software Upgrade

```json
{
  "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:

```python
# 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

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

### Safety Configuration

```yaml
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

```yaml
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](LICENSE) file for details.

---

## 🙏 Acknowledgments

- [FastMCP](https://github.com/jlowin/fastmcp) - Modern MCP framework
- [UV](https://github.com/astral-sh/uv) - Fast Python package manager
- [Cisco SD-WAN](https://www.cisco.com/c/en/us/solutions/enterprise-networks/sd-wan/index.html) - SD-WAN solution
- [Model Context Protocol](https://modelcontextprotocol.io) - MCP specification

---

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/limtsi/sdwan_mcp/issues)
- **Documentation**: [Installation Guide](INSTALLATION_GUIDE.md)
- **MCP Docs**: [Model Context Protocol](https://modelcontextprotocol.io)

---

## 🗺️ 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**