🌐 Network MCP Docker Suite

📚 Example Code for Learning & Development
This is a demonstration project showcasing MCP server implementations for network management. Intended for educational purposes, testing, and development environments.

Docker-based MCP server suite for AIOps - enabling AI-driven network operations through Cisco Meraki, Catalyst Center, IOS XE, ISE, ThousandEyes, Splunk, NetBox & GitLab integration. AI-ready with LibreChat, Cursor, and other MCP clients for intelligent network management, automated troubleshooting, CI/CD orchestration, and operational insights.

🎬 Live Demo

AI-Powered Network Troubleshooting with LibreChat using Multiple MCP Servers

Watch how natural language queries automatically investigate and resolve network issues using both Catalyst Center MCP Server and IOS XE MCP Server. The AI assistant correlates data from management systems (Catalyst Center) with direct device access (IOS XE SSH) to identify root causes and provide comprehensive solutions.

📋 Description

This AIOps-focused Docker suite contains ten MCP servers enabling AI-driven network operations:

• Meraki MCP Server (8000): Cloud network management through Meraki Dashboard API - 📖 Details
• NetBox MCP Server (8001): DCIM/IPAM infrastructure documentation and management - 📖 Details
• Catalyst Center MCP Server (8002): Enterprise network management and assurance - 📖 Details
• IOS XE MCP Server (8003): Direct SSH-based device management - 📖 Details
• ThousandEyes MCP Server (8004): Network performance monitoring and path visualization - 📖 Details
• ISE MCP Server (8005): Identity and access control operations - 📖 Details
• Splunk MCP Server (8006): Log analysis and operational intelligence - 📖 Details
• Prometheus MCP Server (8007): Metrics queries for network monitoring (netops-stack) - 📖 Details
• ClickHouse MCP Server (8008): Syslog and log queries for troubleshooting (netops-stack) - 📖 Details
• GitLab MCP Server (8009): CI/CD pipeline triggering and repository management for network automation - 📖 Details

All servers are containerized with flexible deployment profiles, enabling AIOps workflows through natural language queries, automated troubleshooting, and intelligent network analytics via AI assistants.

🎯 Use Case

Network administrators and DevOps teams face significant challenges in managing modern hybrid network infrastructure across cloud and on-premises environments. This solution addresses these challenges by providing:

🚀 Primary Use Cases

1. Unified Network Operations 🌐

• Single Interface: Manage Meraki cloud networks, on-premises NetBox DCIM/IPAM, Catalyst Center infrastructure, and direct IOS-XE devices through one MCP protocol interface
• Streamlined Workflows: Reduce context switching between multiple network management tools and dashboards
• Cross-Platform Visibility: Correlate data across different network management systems for comprehensive operational insights

2. AI-Powered Network Management 🤖

• Natural Language Queries: Use AI assistants (Cursor, LibreChat) to query network infrastructure using plain English
• Automated Troubleshooting: Enable AI-driven network issue diagnosis by providing unified access to network data
• Intelligent Documentation: Generate automated reports combining real-time network state with infrastructure documentation

3. DevOps Integration & Automation ⚙️

• Infrastructure as Code: Programmatic access to network infrastructure for automation workflows
• CI/CD Integration: Embed network management capabilities into deployment pipelines
• Configuration Management: Standardized API access for network device configuration and monitoring

4. Operational Efficiency 📈

• Role-Based Access: Granular permissions for NOC teams (monitoring + firmware), SysAdmins (read-only), and full API access
• Audit Trail: Comprehensive logging of all network management operations for compliance
• Real-Time Synchronization: Automated synchronization between network devices and documentation systems

🎯 Target Scenarios

📚 Detailed Documentation

For comprehensive use case scenarios and implementation details, see:

• 📖 Detailed Use Case Analysis - Complete business case, technical scenarios, and success metrics
• ☁️ Meraki Server Guide - Cloud network management and Meraki Dashboard API integration
• 📋 NetBox Server Guide - DCIM/IPAM documentation and infrastructure management
• 🏢 Catalyst Center Server Guide - Enterprise network management and assurance operations
• 🔧 IOS XE Server Guide - Direct SSH-based device management capabilities
• 📊 ThousandEyes Server Guide - Network performance monitoring and path visualization
• 🔐 ISE Server Guide - Identity and access control operations
• 📈 Splunk Server Guide - Log analysis and operational intelligence monitoring
• 🦊 GitLab Server Guide - CI/CD pipeline triggering and repository management
• 🤝 Contributing Guidelines - How to extend use cases and add new functionality

🔗 netops-stack Integration

This MCP suite integrates with netops-stack - an observability and orchestration platform for network automation featuring:

• gNMIc - gNMI streaming telemetry collection
• Prometheus - Metrics storage and querying
• ClickHouse - Syslog and log storage via Vector
• Grafana - Visualization dashboards
• GitLab CI/CD - Ansible pipeline orchestration

Use the netops-stack profile to start MCP servers optimized for netops-stack integration:

./deploy.sh start netops-stack   # Starts MCP Servers for: ClickHouse, GitLab, IOS-XE, NetBox, Prometheus

🏗️ Architecture

📐 Deployment Architecture

The suite provides direct access to seven containerized MCP servers, perfect for development, testing, and AI-powered network operations:

┌─────────────────┐    ┌──────────────────────────────────┐
│                 │    │          Docker Host             │
│   MCP Client    │    │                                  │
│                 │    │  ┌─────────────────────────────┐ │
│ • Cursor IDE    │────┼─▶│ Meraki MCP        :8000     │ │
│ • LibreChat     │    │  ├─────────────────────────────┤ │
│ • Claude Desktop│────┼─▶│ NetBox MCP        :8001     │ │
│ • Other MCP     │    │  ├─────────────────────────────┤ │
│   Clients       │────┼─▶│ Catalyst Center   :8002     │ │
│                 │    │  ├─────────────────────────────┤ │
│                 │────┼─▶│ IOS XE MCP        :8003     │ │
│                 │    │  ├─────────────────────────────┤ │
│                 │────┼─▶│ ThousandEyes MCP  :8004     │ │
│                 │    │  ├─────────────────────────────┤ │
│                 │────┼─▶│ ISE MCP           :8005     │ │
│                 │    │  ├─────────────────────────────┤ │
│                 │────┼─▶│ Splunk MCP        :8006     │ │
│                 │    │  ├─────────────────────────────┤ │
│                 │────┼─▶│ Prometheus MCP    :8007     │ │
│                 │    │  ├─────────────────────────────┤ │
│                 │────┼─▶│ ClickHouse MCP    :8008     │ │
│                 │    │  ├─────────────────────────────┤ │
│                 │────┼─▶│ GitLab MCP        :8009     │ │
│                 │    │  └─────────────────────────────┘ │
└─────────────────┘    └──────────────────────────────────┘
        
        Direct HTTP Connections
        ✅ Simple setup - no authentication required
        ✅ Individual server access and configuration
        ✅ Flexible port-based deployment
        ✅ Perfect for development and testing

🎯 Key Architecture Features

• 🐳 Containerized Services: Each MCP server runs in an isolated Docker container
• 🔌 Standard MCP Protocol: Compatible with any MCP client (Cursor, Claude Desktop, LibreChat)
• 📊 Port-Based Access: Each server on dedicated port (8000-8009)
• 🔄 Independent Scaling: Start/stop servers individually as needed
• 🛡️ Network Isolation: Internal Docker network for inter-container communication
• 📝 Comprehensive Logging: JSON-formatted logs with rotation for all services

🧩 Solution Components

🏢 Technical Stack

• MCP Protocol Implementation: Standards-based Model Context Protocol for AI integration
• Docker Containerization: Well-structured containers with security considerations and resource limits
• Network Isolation: Secure communication via Docker networks (mcp-network)
• FastMCP Framework: Modern Python-based MCP server implementation

🚀 Quick Start

📋 Prerequisites

• Docker Engine 20.10+
• Docker Compose 2.0+
• API Access: Valid credentials for the network platforms you want to integrate (see individual server guides for specific requirements)

⚡ 3-Minute Setup

# 1. Clone repository
git clone https://github.com/pamosima/network-mcp-docker-suite.git
cd network-mcp-docker-suite

# 2. Configure environment variables (single .env file for all servers)
cp .env.example .env          # Copy the environment template
nano .env                     # Edit and configure:
                             # - Set ENABLE_*_MCP=false for servers you don't want to use
                             # - Add API keys and credentials for enabled servers
# See .env.example for detailed configuration instructions

# 3. Deploy servers
./deploy.sh start all          # All servers
# OR
./deploy.sh start cisco        # Just Cisco platforms
# OR  
./deploy.sh start meraki       # Just Meraki

# 4. Verify deployment
curl http://localhost:8000/mcp    # Test Meraki server
curl http://localhost:8002/mcp    # Test Catalyst Center server

💡 Quick Tip: All servers now use a single centralized .env file for configuration. Use ENABLE_*_MCP=false to disable servers you don't need, and only add credentials for enabled servers.

🌐 LibreChat Integration: To use with LibreChat on an external network, see the External Network Integration section below.

🎯 Deployment Options

Managing Active Servers

Control which MCP servers run using environment variables in your .env file:

# Enable/Disable individual servers (edit .env)
ENABLE_MERAKI_MCP=true       # Set to false to disable
ENABLE_NETBOX_MCP=true       # Set to false to disable
ENABLE_CATC_MCP=true         # Set to false to disable
ENABLE_IOS_XE_MCP=false      # Disabled - won't start
ENABLE_THOUSANDEYES_MCP=true
ENABLE_ISE_MCP=true
ENABLE_SPLUNK_MCP=false      # Disabled - won't start
ENABLE_PROMETHEUS_MCP=true   # netops-stack metrics
ENABLE_CLICKHOUSE_MCP=true   # netops-stack syslog
ENABLE_GITLAB_MCP=true       # CI/CD orchestration

Best Practices:

• Set ENABLE_*_MCP=false for servers you don't use
• Only configure credentials for enabled servers
• Use deployment profiles (below) to start specific groups
• Reduces resource usage and attack surface

Available Profiles

Deployment Examples

# Flexible deployment using profiles
./deploy.sh start all                        # Complete suite
./deploy.sh start cisco                      # Cisco platforms only
./deploy.sh start monitoring                 # Monitoring focus
./deploy.sh start security                   # Security focus

# Individual servers
./deploy.sh start meraki                     # Cloud management
./deploy.sh start catc                       # Enterprise management
./deploy.sh start ios-xe                     # Direct device access

# Management operations
./deploy.sh status all                       # Check status
./deploy.sh logs cisco                       # View logs
./deploy.sh stop all                         # Stop services

External Network Integration (for LibreChat)

To integrate with LibreChat or other services on an external Docker network:

# 1. Create the external network
docker network create mcp-server

# 2. Copy and use the override configuration
cp docker-compose.override.yml.example docker-compose.override.yml

# 3. Deploy (automatically uses override file)
./deploy.sh start all

The docker-compose.override.yml configures all MCP servers to join the external mcp-server network, allowing seamless communication with LibreChat and other services on the same network.

💻 Usage

🤖 Example Prompts

Here's a real-world example of how to interact with the MCP servers using natural language:

Network Troubleshooting Example

User Prompt:

Check why wlsn-access-1.dna.its-best.ch is unreachable from Cisco Catalyst Center.

AI Assistant Response: The AI assistant automatically uses both MCP servers working together:

1. Catalyst Center MCP Server - Checks device status and issues
2. IOS XE MCP Server - Direct SSH access to verify physical layer
3. Multi-Server Correlation - AI correlates data to identify root cause

Resolution Identified:

• ✅ Device is UP and operational (verified via SSH)
• ✅ Physical connectivity confirmed via CDP
• ❌ Root Cause: IP address mismatch in Catalyst Center inventory
• 🔧 Solution: Update device IP and re-sync

More Example Prompts

🌐 Server Endpoints

🌐 MCP Client Integration

Cursor IDE Configuration

Create or update ~/.cursor/mcp.json:

{
  "mcpServers": {
    "Meraki-MCP-Server": {
      "transport": "http",
      "url": "http://localhost:8000/mcp",
      "timeout": 60000
    },
    "NetBox-MCP-Server": {
      "transport": "http", 
      "url": "http://localhost:8001/mcp",
      "timeout": 60000
    },
    "Catalyst-Center-MCP-Server": {
      "transport": "http",
      "url": "http://localhost:8002/mcp", 
      "timeout": 60000
    },
    "IOS-XE-MCP-Server": {
      "transport": "http",
      "url": "http://localhost:8003/mcp",
      "timeout": 60000
    },
    "ThousandEyes-MCP-Server": {
      "transport": "http",
      "url": "http://localhost:8004/mcp",
      "timeout": 60000
    },
    "ISE-MCP-Server": {
      "transport": "http",
      "url": "http://localhost:8005/mcp",
      "timeout": 60000
    },
    "Splunk-MCP-Server": {
      "transport": "http",
      "url": "http://localhost:8006/mcp",
      "timeout": 60000
    },
    "Prometheus-MCP-Server": {
      "transport": "http",
      "url": "http://localhost:8007/mcp",
      "timeout": 60000
    },
    "ClickHouse-MCP-Server": {
      "transport": "http",
      "url": "http://localhost:8008/mcp",
      "timeout": 60000
    },
    "GitLab-MCP-Server": {
      "transport": "http",
      "url": "http://localhost:8009/mcp",
      "timeout": 60000
    }
  }
}

LibreChat Configuration

Add to your librechat.yaml:

mcpServers:
  Meraki-MCP-Server:
    type: streamable-http
    url: http://meraki-mcp-server:8000/mcp
    timeout: 60000
  Netbox-MCP-Server:
    type: streamable-http
    url: http://netbox-mcp-server:8001/mcp
    timeout: 60000
  CatC-MCP-Server:
    type: streamable-http
    url: http://catc-mcp-server:8002/mcp
    timeout: 60000
  IOS-XE-MCP-Server:
    type: streamable-http
    url: http://ios-xe-mcp-server:8003/mcp
    timeout: 60000
  ThousandEyes-MCP-Server:
    type: streamable-http
    url: http://thousandeyes-mcp-server:8004/mcp
    timeout: 60000
  ISE-MCP-Server:
    type: streamable-http
    url: http://ise-mcp-server:8005/mcp
    timeout: 60000
  Splunk-MCP-Server:
    type: streamable-http
    url: http://splunk-mcp-server:8006/mcp
    timeout: 60000
  Prometheus-MCP-Server:
    type: streamable-http
    url: http://prometheus-mcp-server:8007/mcp
    timeout: 60000
  ClickHouse-MCP-Server:
    type: streamable-http
    url: http://clickhouse-mcp-server:8008/mcp
    timeout: 60000
  GitLab-MCP-Server:
    type: streamable-http
    url: http://gitlab-mcp-server:8009/mcp
    timeout: 60000

🔧 Management Commands

Basic Operations

# Deploy services
./deploy.sh start all          # All servers
./deploy.sh start cisco        # Cisco platforms
./deploy.sh start monitoring   # Monitoring focused

# Check status
./deploy.sh status all         # All services
docker-compose ps              # Docker status

# View logs  
./deploy.sh logs all           # All services
./deploy.sh logs meraki        # Specific server

# Stop services
./deploy.sh stop all           # All services
docker-compose down            # Docker stop

# Update and rebuild
git pull                       # Get updates
docker-compose up -d --build   # Rebuild and restart

Quick Verification

# Test all servers are responding
curl http://localhost:8000/mcp    # Meraki
curl http://localhost:8001/mcp    # NetBox
curl http://localhost:8002/mcp    # Catalyst Center
curl http://localhost:8003/mcp    # IOS XE
curl http://localhost:8004/mcp    # ThousandEyes
curl http://localhost:8005/mcp    # ISE
curl http://localhost:8006/mcp    # Splunk
curl http://localhost:8007/mcp    # Prometheus
curl http://localhost:8008/mcp    # ClickHouse
curl http://localhost:8009/mcp    # GitLab

🔒 Security Considerations

Container Security

• ✅ Runs as non-root user
• ✅ Security options enabled (no-new-privileges)
• ✅ Resource limits configured
• ✅ Network isolation via Docker networks

Production Security

• 🔒 API keys loaded from environment variables only
• 🔒 Network isolation via Docker networks
• 🔒 Role-based access control (where supported)

For production deployments, consider:

1. Secrets Management: Use Docker secrets or external secret managers
2. Network Security: Implement proper firewall rules and network segmentation
3. Monitoring: Set up comprehensive logging and monitoring
4. Updates: Regular security updates and vulnerability scanning

🔧 Troubleshooting

Common Issues

Servers not responding:

# Check if containers are running
./deploy.sh status all

# Check logs for errors
./deploy.sh logs all

# Restart problematic services
./deploy.sh restart <profile>

MCP clients can't connect:

# Verify endpoints are accessible
curl http://localhost:8000/mcp

# Check network connectivity
docker network ls
docker network inspect <network_name>

# Restart MCP client (Cursor, LibreChat, etc.)

Configuration issues:

• Check the centralized .env file for correct credentials
• Verify API keys and passwords are properly set (not example placeholders)
• Check individual server READMEs for detailed troubleshooting
• Verify API credentials have appropriate permissions
• Check network connectivity to target systems

📊 Monitoring and Maintenance

Health Checks

# Check all services
./deploy.sh status all

# Monitor resource usage
docker stats

# View recent logs
./deploy.sh logs all | tail -100

Updates

# Pull latest changes
git pull

# Rebuild and restart
docker-compose up -d --build

# Clean up old images
docker system prune -f

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines for details on our code of conduct and the process for submitting pull requests.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Test with docker-compose up -d --build
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📄 License

This project is licensed under the Cisco Sample Code License, Version 1.1 - see the LICENSE file for details.

🙏 Acknowledgments

Special thanks to:

• kiskander for the original Meraki MCP Server implementation that inspired the Meraki component of this comprehensive multi-server suite.

• tspuhler for the IOS XE MCP Server implementation, providing direct SSH-based device management capabilities for Cisco IOS XE devices.

• Aditya Chellam and Kiran Kabdal for the ThousandEyes MCP Community server implementation. The ThousandEyes MCP Server in this suite is based on their comprehensive ThousandEyes v7 API integration.

• automateyournetwork (John Capobianco) and RobertBergman for the ISE MCP Server implementation. The ISE MCP Server in this suite is based on their comprehensive ISE ERS API integration for network access control and security operations.

⚠️ Disclaimer

This project is part of the Cisco DevNet community and is provided as example code for demonstration and learning purposes. It is not officially supported by Cisco Systems and is not intended for production use without proper testing and customization for your specific environment.