Cisco Server

Production-grade Model Context Protocol (MCP) server for executing Cisco CLI commands on network devices over SSH.

Architecture

MCP Client (LLM)
       ↓
   Tool Selection
   ┌─────────────────────┐
   │ execute_exec_command │  ← show, ping, clear, traceroute, dir
   │ execute_config_command│  ← interface, hostname, router, acl
   └─────────────────────┘
       ↓
Validation Layer (validator)
       ↓
Connector Layer (cisco.py)
       ↓
SSH Transport (Scrapli + Paramiko)
       ↓
Cisco Device

Features

• Two MCP Tools: LLM decides whether to call the exec or config tool
  • execute_exec_command — operational/exec mode commands (show, ping, clear, traceroute, etc.)
  • execute_config_command — configuration mode commands (interface, hostname, router, etc.)
• Configuration Mode Management: Automatically handles enable → configure terminal → commands → end
• Pagination Handling: Automatically disables pagination (terminal length 0) for exec commands
• Dangerous Command Blocking: Rejects reload, write erase, debug, etc.
• Managed Command Rejection: Rejects conf t, enable, end, exit (server manages these)
• Structured Audit Logging: JSON-line audit trail for every execution
• Legacy SSH Support: Paramiko transport for devices with older SSH (e.g., diffie-hellman-group1-sha1)
• Vendor Extensible: Abstract base connector supports future vendors (Juniper, Arista, etc.)

Project Structure

mcp_server/
├── server.py                  # MCP server entry point (two tools registered)
├── config.py                  # Configuration management (env vars)
├── models.py                  # Pydantic request/response models
├── tools/
│   └── execute_commands.py    # ExecCommandTool + ConfigCommandTool
├── connectors/
│   ├── base.py                # Abstract base connector
│   └── cisco.py               # Cisco IOS/IOS-XE connector (Scrapli + Paramiko)
├── validation/
│   ├── classifier.py          # Command classifier (kept for reference/utility)
│   └── validator.py           # Input validator (dangerous cmds, device check)
├── inventory/
│   └── devices.yaml           # Device inventory
├── audit/
│   └── audit_logger.py        # Structured audit logger
├── utils/
│   ├── logger.py              # Logging configuration
│   └── exceptions.py          # Custom exceptions
└── tests/
    ├── test_classifier.py
    ├── test_validator.py
    ├── test_models.py
    └── test_execute_commands.py

Setup

Prerequisites

• Python 3.11+
• Access to Cisco devices via SSH

Installation

# Clone and enter project directory
cd Cicsco_MCP_New

# Create virtual environment
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt

Configuration

1. Copy the environment template:

copy .env.example .env

2. Edit .env with your credentials:

CISCO_USERNAME=admin
CISCO_PASSWORD=your_password
CISCO_ENABLE_PASSWORD=your_enable_password
SSH_TIMEOUT=30
SSH_PORT=22
LOG_LEVEL=INFO

3. Edit mcp_server/inventory/devices.yaml to add your devices:

devices:
  "10.10.10.1":
    hostname: "R1"
    platform: "cisco_iosxe"
    description: "Core Router"

Note: If devices.yaml is empty or missing, the server allows connections to any device.

Running the Server

Standalone (stdio transport)

python -m mcp_server.server

Testing with MCP Inspector

npx @modelcontextprotocol/inspector python -m mcp_server.server

Opens a browser UI where you can select either tool and test with real devices.

VS Code / Claude Desktop Integration

Add to your MCP client configuration:

{
  "mcpServers": {
    "cisco": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "C:/path/to/Cicsco_MCP_New"
    }
  }
}

Usage

Tool 1: execute_exec_command

For operational/exec mode commands — the LLM calls this for show, ping, clear, traceroute, etc.

Request:

{
  "device": "10.10.10.1",
  "commands": [
    "show version",
    "show ip interface brief"
  ]
}

Response:

{
  "success": true,
  "mode": "exec",
  "device": "10.10.10.1",
  "execution_time": 2.31,
  "results": [
    {
      "command": "show version",
      "output": "Cisco IOS XE Software, Version 17.03.04a..."
    },
    {
      "command": "show ip interface brief",
      "output": "Interface              IP-Address      OK? Method Status..."
    }
  ]
}

Tool 2: execute_config_command

For configuration mode commands — the LLM calls this for interface, routing, ACL changes, etc. The server automatically handles enable → configure terminal → commands → end.

Request:

{
  "device": "10.10.10.1",
  "commands": [
    "interface Loopback100",
    "ip address 10.100.0.1 255.255.255.0",
    "no shutdown"
  ]
}

Response:

{
  "success": true,
  "mode": "config",
  "device": "10.10.10.1",
  "execution_time": 1.92,
  "results": [
    {
      "command": "interface Loopback100",
      "status": "success"
    },
    {
      "command": "ip address 10.100.0.1 255.255.255.0",
      "status": "success"
    },
    {
      "command": "no shutdown",
      "status": "success"
    }
  ]
}

Error Responses

Authentication failure:

{
  "success": false,
  "device": "10.10.10.1",
  "error": "Authentication failed for device 10.10.10.1."
}

Blocked dangerous command:

{
  "success": false,
  "device": "10.10.10.1",
  "error": "Blocked dangerous command: 'reload'"
}

Managed command rejected:

{
  "success": false,
  "device": "10.10.10.1",
  "error": "Command 'configure terminal' is managed automatically by the server. Do not include it in the command list."
}

Running Tests

pytest mcp_server/tests/ -v

Security

• All inputs are validated before any device connection
• Dangerous commands are blocked at the validation layer
• No shell commands are executed on the MCP server host
• Credentials are loaded from environment variables (never hardcoded)
• SSH connections use secure authentication
• Audit logs record every execution for compliance

Extending for Other Vendors

To add support for a new vendor (e.g., Juniper):

1. Create mcp_server/connectors/juniper.py
2. Implement the BaseConnector interface
3. Update device inventory with platform type

The tool, validation, and audit layers remain unchanged.

License

Internal use only.