SDWAN-MCP-SERVER

# 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!