Netzwerk-MCP-Server

Ein Model Context Protocol (MCP)-Server, der es einem KI-Agenten ermöglicht, über SSH mit einem Cisco IOS-XE-Netzwerkgerät zu interagieren. Erstellt in Python mit FastMCP und Netmiko.

Der Server stellt 7 Tools bereit (5 Lese- + 2 Schreib-Tools), jedes mit strenger Eingabevalidierung und klaren Beschreibungen, sodass ein LLM-Agent sie autonom entdecken und verwenden kann.

Kurs: Agent AI & Automation — Sheridan College Autor: Ahmed Dozent: Sebastian

Inhaltsverzeichnis

1. Laborumgebung

2. Installation

3. Server ausführen

4. Tools

5. Verbindung mit Claude Desktop

6. Beispielinteraktionen

7. Erforderliche Berechtigungen

8. Sicherheitshinweise

9. Fehlerbehebung

Laborumgebung

Dieses Projekt zielt auf Ciscos Always-On IOS-XE DevNet Sandbox ab. Sie ist kostenlos, öffentlich erreichbar, erfordert keine Reservierung und ist immer verfügbar.

Referenz: Cisco DevNet — Always-On Sandboxes.

Schneller Konnektivitätstest von Ihrem Rechner:

ssh admin@sandbox-iosxe-latest-1.cisco.com
# password: C1sco12345

Sie sollten an einem Router# (oder ähnlichen) Prompt landen. Wenn dies funktioniert, wird auch der MCP-Server funktionieren.

Die Sandbox wird geteilt. Bitte halten Sie Änderungen klein und nicht störend (z. B. nur Schnittstellenbeschreibungen bearbeiten, keine Schnittstellen herunterfahren oder IPs ändern).

Installation

Erfordert Python 3.10+.

# 1. Clone / copy the project
cd network-mcp-server

# 2. Create and activate a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate    # on Windows: .venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

Abhängigkeiten:

• mcp[cli] — MCP Python SDK (bietet FastMCP)

• netmiko — Multi-Vendor SSH/CLI-Bibliothek

• python-dotenv — lädt .env für die lokale Entwicklung

Server ausführen

Option A — Standalone (für lokale Tests)

cp .env.example .env
# edit .env if your lab uses different credentials

python server.py

Der Server läuft über stdio, wartet also auf stdin für MCP JSON-RPC-Nachrichten. In der Praxis rufen Sie ihn nicht manuell auf — Sie verbinden Claude Desktop (siehe unten) oder das mcp Dev-CLI.

Option B — Interaktiver Dev-Inspector

mcp dev server.py

Dies öffnet den MCP-Inspector in Ihrem Browser, wo Sie Tools auflisten und manuell aufrufen können.

Tools

Lese-Tools

Schreib-Tools

Alle Tool-Ausgaben sind JSON-Strings, damit das LLM strukturierte Daten verarbeiten kann. Wenn die TextFSM-Parser von Netmiko eine Ausgabe nicht verarbeiten können, greift der Server auf rohen CLI-Text innerhalb eines {"raw": "..."}-Wrappers zurück.

Verbindung mit Claude Desktop

1. Suchen Sie die Konfigurationsdatei von Claude Desktop:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Fügen Sie den folgenden Block in die Datei ein (verwenden Sie den vollständigen absoluten Pfad zu Ihrer server.py):

{
  "mcpServers": {
    "network-mcp-server": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/network-mcp-server/server.py"],
      "env": {
        "DEVICE_HOST": "sandbox-iosxe-latest-1.cisco.com",
        "DEVICE_PORT": "22",
        "DEVICE_USERNAME": "admin",
        "DEVICE_PASSWORD": "C1sco12345",
        "DEVICE_TYPE": "cisco_xe"
      }
    }
  }
}

Eine kopierfertige Version befindet sich in claude_desktop_config.example.json.

3. Beenden Sie Claude Desktop vollständig und starten Sie es neu. (Das bloße Schließen des Fensters reicht nicht aus — der MCP-Prozess bleibt im Hintergrund aktiv.)

4. Klicken Sie in einem neuen Chat auf das 🛠️ / Tools-Symbol. Sie sollten network-mcp-server mit 7 Tools aufgelistet sehen.

Beispielinteraktionen

Sobald die Verbindung steht, probieren Sie diese Prompts:

"Mit welchem Gerät bin ich verbunden? Gib mir den Hostnamen, das Modell und die IOS-Version." Der Agent ruft get_device_info auf.

"Liste alle Schnittstellen auf, denen derzeit eine IP-Adresse zugewiesen ist." Der Agent ruft get_interfaces auf und filtert die Ergebnisse.

"Zeig mir die Standardroute." Der Agent ruft get_routes auf und wählt den Eintrag mit dem Netzwerk 0.0.0.0 aus.

"Setze die Beschreibung auf GigabitEthernet2 auf 'managed by MCP demo' und bestätige dann, dass die Änderung angewendet wurde." Der Agent ruft configure_interface_description auf und anschließend (optional) get_running_config mit section='interface GigabitEthernet2', um dies zu überprüfen.

"Speichere die laufende Konfiguration in die Startup-Konfiguration." Der Agent ruft save_config auf.

Erforderliche Berechtigungen

Der MCP-Server benötigt:

1. Netzwerk-Egress vom Host-Rechner zum SSH-Port des Geräts (standardmäßig TCP/22). In Unternehmensnetzwerken benötigen Sie möglicherweise ein VPN oder einen Proxy.

2. Ein Gerätekonto mit Privileged Exec-Rechten — das admin-Konto der DevNet-Sandbox ist bereits auf Enable-Ebene. Wenn Sie Ihr eigenes Gerät verwenden, muss das Konto in der Lage sein, config t einzugeben und write memory auszuführen.

3. Lokalen Lesezugriff auf die .env-Datei oder entsprechende Umgebungsvariablen, die von Claude Desktop gesetzt werden.

Der Server benötigt keine Root-/Admin-Rechte auf Ihrer Workstation.

Sicherheitshinweise

• Anmeldedaten sind niemals hartcodiert. Sie stammen aus Umgebungsvariablen (DEVICE_USERNAME, DEVICE_PASSWORD). Wenn eine erforderliche Umgebungsvariable fehlt, verweigert der Server die Verbindung und gibt einen klaren Fehler zurück.

• .env ist in git ignoriert. Stattdessen wird eine .env.example (mit sicher zu teilenden DevNet-Sandbox-Werten) bereitgestellt.

• Eingabevalidierung bei jedem Tool. Schnittstellennamen, Beschreibungen und Konfigurationsabschnittsfilter werden alle per Regex validiert, bevor sie das Geräte-CLI erreichen. Shell-Metazeichen (;, |, Backtick, Zeilenumbruch, Null-Byte) werden abgelehnt.

• Anmeldedaten werden niemals als Tool-Argumente offengelegt. Das LLM kann sie nicht lesen, protokollieren oder exfiltrieren — es sieht nur die Tool-Ausgaben.

• Schreib-Tools beinhalten eine Überprüfung. configure_interface_description liest die Konfiguration nach dem Anwenden der Änderung erneut aus und meldet applied: true/false.

• Der Umfang ist begrenzt. Die beiden Schreib-Tools können nur Schnittstellenbeschreibungen ändern und die Konfiguration speichern. Destruktive Operationen (Shutdown, IP-Adressänderung, VLAN-Löschung, erase startup-config) sind bewusst nicht verfügbar.

Fehlerbehebung

"Missing required environment variable(s)" Sie haben vergessen, DEVICE_HOST / DEVICE_USERNAME / DEVICE_PASSWORD zu setzen. Kopieren Sie .env.example nach .env oder setzen Sie sie im env-Block von Claude Desktop.

"Authentication to failed" Überprüfen Sie das Passwort. Wenn Sie die Sandbox geändert haben oder ein anderes Gerät verwenden, stellen Sie sicher, dass SSH aktiviert ist und das Konto über Privileged-Exec-Zugriff verfügt.

"Connection to timed out" Der Netzwerk-Egress ist blockiert. Versuchen Sie ssh admin@sandbox-iosxe-latest-1.cisco.com von demselben Rechner aus. Wenn das ebenfalls hängt, ist Ihre Firewall/VPN das Problem.

Claude Desktop zeigt den Server nach dem Bearbeiten der Konfiguration nicht an Beenden Sie Claude Desktop vollständig (nicht nur das Fenster schließen) und öffnen Sie es erneut. Unter macOS: Cmd+Q. Unter Windows: Rechtsklick auf das Tray-Symbol → Beenden.

Tool-Aufruf gibt rohen Text statt geparstem JSON zurück Dies bedeutet, dass das TextFSM-Template von Netmiko nicht mit der Geräteausgabe übereinstimmte (andere IOS-Version, andere Plattform). Der Server greift auf rohen CLI-Text in {"raw": "..."} zurück. Der Agent kann ihn dennoch verarbeiten; er ist nur nicht strukturiert.