Content
# SD-WAN MCP Server
A comprehensive Model Context Protocol (MCP) server for monitoring and managing SD-WAN devices through REST API endpoints. This server exposes SD-WAN device monitoring and management functionality that can be integrated with Cursor and other MCP-compatible tools.
## 🚀 Features
- **🔧 Device Management**: List and monitor SD-WAN fabric devices
- **📊 Statistics Collection**: Interface statistics, device counters, tunnel statistics
- **🔍 BFD Monitoring**: Bidirectional Forwarding Detection state and sessions
- **⚙️ Configuration Access**: Device configuration retrieval
- **📈 Advanced Analytics**: Health summaries, traffic analysis, and alerting
- **🔐 Session Management**: Automatic authentication and session handling
- **⚡ Async Support**: Full async/await support for non-blocking operations
- **🎯 Cursor Integration**: Seamless integration with Cursor IDE
## 📋 Available Tools
### Basic Monitoring Tools
1. **get_fabric_devices** - Get list of all SD-WAN fabric devices
2. **get_device_monitor** - Get SD-WAN device monitoring information
3. **get_device_counters** - Get SD-WAN device counters and statistics
4. **get_interface_statistics** - Get interface statistics for all SD-WAN devices
5. **get_device_config** - Get SD-WAN device configuration (requires device_id)
6. **get_bfd_state** - Get BFD state for an SD-WAN device (requires device_id)
7. **get_bfd_sessions** - Get BFD sessions for an SD-WAN device (requires device_id)
8. **get_tunnel_statistics** - Get tunnel statistics for an SD-WAN device (requires device_id)
### Authentication Tools
9. **authenticate** - Authenticate with the SD-WAN management server
10. **get_session_status** - Check current authentication session status
### Advanced Analytics Tools
11. **get_device_health_summary** - Comprehensive health summary across all SD-WAN devices
12. **filter_devices_by_status** - Filter SD-WAN devices by operational status
13. **get_top_interfaces_by_traffic** - Get top interfaces ranked by traffic utilization
14. **check_bfd_session_health** - Monitor BFD session health across all SD-WAN devices
15. **generate_network_report** - Generate comprehensive SD-WAN network status report
16. **get_device_alerts** - Get alerts and warnings for SD-WAN devices by severity
17. **monitor_interface_utilization** - Monitor interface utilization with configurable thresholds
18. **get_network_topology** - Get SD-WAN network topology information
## 🛠️ Quick Start
### Prerequisites
- Python 3.8 or higher
- Access to SD-WAN management server
- Cursor IDE (for integration)
### Installation
1. **Clone the repository**
```bash
git clone https://github.com/yourusername/sdwan-mcp-server.git
cd sdwan-mcp-server
```
2. **Install dependencies**
```bash
pip install -r requirements.txt
```
3. **Configure environment variables**
```bash
# Copy the example environment file
cp .env.example .env
# Edit .env with your settings
nano .env
```
4. **Update configuration**
⚠️ **IMPORTANT**: You must update the IP address in your configuration!
Edit your `.env` file:
```bash
# REQUIRED: Change this to your SD-WAN management server IP
SDWAN_BASE_URL="https://YOUR_SDWAN_SERVER_IP:8443"
# Update credentials
SDWAN_USERNAME="your_username"
SDWAN_PASSWORD="your_password"
# Optional settings
VERIFY_SSL="false"
LOG_LEVEL="INFO"
```
5. **Test the server**
```bash
python test_client.py
```
6. **Run the server**
```bash
python main.py
```
## ⚙️ Configuration
### Environment Variables
| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `SDWAN_BASE_URL` | SD-WAN server base URL | `https://192.168.10.130:8443` | ✅ **YES** |
| `SDWAN_USERNAME` | Authentication username | `admin` | ✅ **YES** |
| `SDWAN_PASSWORD` | Authentication password | `1` | ✅ **YES** |
| `VERIFY_SSL` | Enable SSL certificate verification | `false` | No |
| `LOG_LEVEL` | Logging level (DEBUG, INFO, WARNING, ERROR) | `INFO` | No |
| `SESSION_TIMEOUT` | Session timeout in seconds | `3600` | No |
| `AUTO_RECONNECT` | Auto-reconnect on session expiry | `true` | No |
### Configuration Methods
#### Method 1: Environment Variables (Recommended)
```bash
export SDWAN_BASE_URL="https://your-sdwan-server:8443"
export SDWAN_USERNAME="admin"
export SDWAN_PASSWORD="your_password"
python main.py
```
#### Method 2: .env File
```bash
# Create .env file
echo "SDWAN_BASE_URL=https://your-sdwan-server:8443" > .env
echo "SDWAN_USERNAME=admin" >> .env
echo "SDWAN_PASSWORD=your_password" >> .env
python main.py
```
#### Method 3: Direct Configuration
Edit `config.py` to change default values (not recommended for production).
## 🔧 Cursor Integration
### Option 1: MCP Configuration File
1. Create or update your MCP configuration file:
```json
{
"mcpServers": {
"sdwan-mcp-server": {
"command": "python",
"args": ["/full/path/to/your/project/main.py"],
"env": {
"SDWAN_BASE_URL": "https://your-sdwan-server:8443",
"SDWAN_USERNAME": "admin",
"SDWAN_PASSWORD": "your_password"
}
}
}
}
```
2. Update the path to point to your `main.py` file
3. Restart Cursor
### Option 2: Cursor Settings
Add to your Cursor settings:
```json
{
"mcp": {
"servers": {
"sdwan-mcp-server": {
"command": "python",
"args": ["/full/path/to/main.py"]
}
}
}
}
```
## 💡 Usage Examples
Once integrated with Cursor, you can use natural language queries:
### Basic Queries
- "Show me all SD-WAN fabric devices"
- "Get the SD-WAN interface statistics"
- "Check BFD state for SD-WAN device 200.0.1.1"
- "Get tunnel statistics for SD-WAN device 200.0.2.2"
### Advanced Analytics
- "Give me a comprehensive health summary of the SD-WAN network"
- "Show me all SD-WAN devices that are currently down"
- "What are the top 10 interfaces by traffic volume?"
- "Generate a full SD-WAN network report"
- "Which interfaces are using more than 80% bandwidth?"
### Troubleshooting
- "Check if I'm authenticated to the SD-WAN server"
- "Show me all critical alerts in the SD-WAN network"
- "What SD-WAN devices need immediate attention?"
## 🏗️ Project Structure
```
sdwan-mcp-server/
├── main.py # Main MCP server implementation
├── config.py # Configuration management
├── test_client.py # Test client for validation
├── requirements.txt # Python dependencies
├── setup.py # Package setup
├── mcp_config.json # MCP configuration template
├── .env.example # Environment variables template
├── .gitignore # Git ignore file
├── LICENSE # MIT license
└── README.md # This file
```
## 🔍 API Endpoints
The server connects to these SD-WAN management API endpoints:
- `/dataservice/device` - Fabric devices
- `/dataservice/device/monitor` - Device monitoring
- `/dataservice/device/counters` - Device counters
- `/dataservice/statistics/interface` - Interface statistics
- `/dataservice/device/config` - Device configuration
- `/dataservice/device/bfd/state/device` - BFD state
- `/dataservice/device/bfd/sessions` - BFD sessions
- `/dataservice/device/tunnel/statistics` - Tunnel statistics
## 🐛 Troubleshooting
### Common Issues
1. **Connection Errors**
```bash
# Check if your SD-WAN server is accessible
curl -k https://YOUR_SDWAN_SERVER_IP:8443
```
2. **Authentication Errors**
```bash
# Verify credentials
export SDWAN_USERNAME="correct_username"
export SDWAN_PASSWORD="correct_password"
```
3. **SSL Certificate Issues**
```bash
# Disable SSL verification for self-signed certificates
export VERIFY_SSL="false"
```
4. **Import Errors**
```bash
# Install missing dependencies
pip install -r requirements.txt
```
### Debug Mode
Enable detailed logging:
```bash
export LOG_LEVEL="DEBUG"
python main.py
```
### Testing Connection
```bash
# Test authentication
python -c "
import asyncio
from main import SDWANMCPServer
async def test():
server = SDWANMCPServer()
result = await server._authenticate()
print(result)
asyncio.run(test())
"
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🆘 Support
- **Issues**: [GitHub Issues](https://github.com/yourusername/sdwan-mcp-server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/sdwan-mcp-server/discussions)
## 🙏 Acknowledgments
- Built with [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol)
- Designed for [Cursor IDE](https://cursor.sh/) and [CLAUDE DESKTOP]
- SD-WAN management capabilities
---
⚠️ **Remember**: Always update the `SDWAN_BASE_URL` to match your SD-WAN management server's IP address!
