stormbliss/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

   git clone https://github.com/yourusername/sdwan-mcp-server.git
   cd sdwan-mcp-server
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Configure environment variables

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

   # 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

   python test_client.py
   

6. Run the server

   python main.py
   

⚙️ Configuration

Environment Variables

Configuration Methods

Method 1: Environment Variables (Recommended)

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

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

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

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

   # Check if your SD-WAN server is accessible
   curl -k https://YOUR_SDWAN_SERVER_IP:8443
   

2. Authentication Errors

   # Verify credentials
   export SDWAN_USERNAME="correct_username"
   export SDWAN_PASSWORD="correct_password"
   

3. SSL Certificate Issues

   # Disable SSL verification for self-signed certificates
   export VERIFY_SSL="false"
   

4. Import Errors

   # Install missing dependencies
   pip install -r requirements.txt
   

Debug Mode

Enable detailed logging:

export LOG_LEVEL="DEBUG"
python main.py

Testing Connection

# 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 file for details.

🆘 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

🙏 Acknowledgments

• Built with Model Context Protocol (MCP)
• Designed for Cursor IDE and [CLAUDE DESKTOP]
• SD-WAN management capabilities

⚠️ Remember: Always update the SDWAN_BASE_URL to match your SD-WAN management server's IP address!