ISE MCP Server

ISE MCP-Server (mit FastMCP)

Überblick

Der ISE MCP Server ist ein Model Context Protocol (MCP) -Server, der mit der Python-Bibliothek fastmcp erstellt wurde. Er stellt API-Endpunkte der Cisco Identity Services Engine (ISE) dynamisch als strukturierte, auffindbare MCP-Tools bereit. Dieser Server ermöglicht Clients die standardisierte Interaktion mit Cisco ISE REST-APIs und bietet Funktionen wie die dynamische Toolgenerierung und API-Antwortfilterung.

Merkmale

• Dynamische Tool-Generierung: MCP-Tools werden automatisch basierend auf Einträgen in der Konfigurationsdatei src/ise_mcp_server/urls.json erstellt.
• FastMCP-Integration: Nutzt die fastmcp -Bibliothek für eine robuste MCP-Serverimplementierung, einschließlich Schemagenerierung und Anforderungsverarbeitung.
• Asynchrone API-Aufrufe: Verwendet httpx.AsyncClient für die nicht blockierende Kommunikation mit Cisco ISE.
• API-Filterung: Unterstützt das Filtern von Cisco ISE API-Ergebnissen durch die Argumente filter_expression und query_params in jedem Tool.
• Umgebungsgesteuerte Konfiguration: Cisco ISE-Verbindungsdetails (Basis-URL, Benutzername, Passwort) und SSL-Verifizierungseinstellungen ( ISE_VERIFY_SSL ) werden über eine .env Datei konfiguriert.
• Detaillierte Docstrings: Dynamisch generierte Tools enthalten umfassende Docstrings, die ihren Zweck, den ISE-API-Endpunkt, auf den sie abzielen, und die Verwendung von Filterparametern erklären.
• Standardisierte Interaktion: Hält sich an das Model Context Protocol und ermöglicht die Interaktion über jeden MCP-kompatiblen Client.
• Streamable-HTTP-Transport: Standardmäßig so konfiguriert, dass für den webbasierten Zugriff streamable-http -Transport verwendet wird.

Aufstellen

Server

{ "mcpServers": { "ise": { "Befehl": "python", "Argumente": [ "ise_mcp_server.py", "--oneshot" ], "Umgebung": { "ISE_BASE": " https://devnetsandboxise.cisco.com ", "BENUTZERNAME": "schreibgeschützt", "PASSWORT": "ISEisC00L" } } } }

Anforderungen

• Python 3.9 oder höher.
• Erforderliche Python-Pakete sind in der requirements.txt (im Projektstammverzeichnis) aufgeführt. Installieren Sie sie mit:
  pip install -r requirements.txt
  Oder, wenn Sie uv verwenden:
  uv pip install -r requirements.txt
  Zu den wichtigsten Abhängigkeiten zählen fastmcp , httpx , pydantic und python-dotenv . (Stellen Sie sicher, dass requirements.txt``httpx anstelle von requests widerspiegelt.)

Konfiguration

1. Umgebungsvariablen: Erstellen Sie eine .env Datei im Stammverzeichnis des Projekts ( /Users/username/mcp_servers/ISE_MCP/.env ) mit Ihren Cisco ISE-API-Anmeldeinformationen und der Basis-URL:
   ISE_BASE="https://your-ise-instance.example.com" USERNAME="your-ise-api-username" PASSWORD="your-ise-api-password" # Optional: Controls SSL certificate verification for ISE API calls. # Default is true. Set to "false" to disable (insecure). # Or provide a path to a CA bundle file, e.g., "/path/to/your/ca.pem". ISE_VERIFY_SSL="true"
2. URL-Konfiguration ( urls.json ): Stellen Sie sicher, dass die Datei src/ise_mcp_server/urls.json (im selben Verzeichnis wie src/ise_mcp_server/server.py ) vorhanden und korrekt strukturiert ist. Diese Datei definiert die ISE-API-Endpunkte, die als MCP-Tools bereitgestellt werden.
   [ { "URL": "/ers/config/endpoint", "Name": "Endpoints", "FilterableFields": ["mac", "name", "description", "identityGroupName"] }, { "URL": "/ers/config/identitygroup", "Name": "Identity Groups", "FilterableFields": ["name", "description"] } // ... more endpoints ]
   • URL : Der relative Pfad des Cisco ISE API-Endpunkts.
   • Name : Ein für Menschen lesbarer Name, aus dem der Name des MCP-Tools abgeleitet wird (z. B. wird aus „Endpoints“ das Tool „ endpoints “).
   • FilterableFields : Ein Array von Zeichenfolgen mit bekannten Feldern, die mit dem filter_expression für diesen Endpunkt verwendet werden können. Diese Liste wird vom Benutzer verwaltet und ist für eine effektive Filterung unerlässlich.

Ausführen des Servers mit Docker für Claude Desktop

Dieser Server ist für die Ausführung als Docker-Container konzipiert, insbesondere bei Verwendung mit Clients wie Claude Desktop, die über STDIO interagieren.

Voraussetzungen

1. Docker installiert: Stellen Sie sicher, dass Docker Desktop installiert und ausgeführt wird.
2. .env -Datei: Ihre .env Datei (wie unter „Konfiguration“ beschrieben) muss im Projektstammverzeichnis ( /Users/username/mcp_servers/ISE_MCP/.env ) vorhanden sein.
3. Dockerfile für STDIO konfiguriert: Das Dockerfile in diesem Projekt ( Dockerfile ) sollte für die Verwendung stdio -Transport konfiguriert sein. Der ENTRYPOINT sollte wie folgt aussehen:
   ENTRYPOINT ["python", "-m", "ise_mcp_server", "--transport", "stdio"]
   Stellen Sie sicher, dass die .env Datei nicht kopiert wird.

Erstellen Sie das Docker-Image

Navigieren Sie zum Verzeichnis, das die Docker-Datei enthält ( /Users/username/mcp_servers/ISE_MCP/ ), und erstellen Sie das Docker-Image:

Alternativ, wenn Sie vom Projektstamm aus erstellen:

Claude Desktop konfigurieren

Aktualisieren Sie Ihre Claude Desktop MCP-Serverkonfiguration ( claude_desktop_config.json oder cline_mcp_settings.json ) für den „ISE_MCP“-Server wie folgt:

Erklärung der Docker-Argumente:

• run : Führt den Docker-Container aus.
• -i : (Interaktiv) Hält STDIN geöffnet, auch wenn es nicht angeschlossen ist, entscheidend für die STDIO-basierte MCP-Kommunikation.
• --rm : Entfernt den Container automatisch, wenn er beendet wird.
• --env-file : Gibt den Pfad zu Ihrer .env Datei auf Ihrem Hostcomputer an. Docker lädt diese Variablen in den Container.
• ise-mcp:latest : Der Name und das Tag des auszuführenden Docker-Images.
• cwd : Legt das Arbeitsverzeichnis für den Befehl fest und stellt sicher, dass relative Pfade (wie für --env-file ) korrekt aufgelöst werden, wenn Claude Desktop Befehle aus einem anderen Standardverzeichnis ausführt.

Ausführen mit Docker Compose (Alternative für lokale Tests)

Für lokale Tests steht außerdem eine docker-compose.yml Datei zur Verfügung. Diese erstellt das Image und führt den Container aus. Dabei werden Umgebungsvariablen aus der .env Datei geladen.

Diese Methode eignet sich für direkte Tests, für die Claude Desktop-Integration wird jedoch die obige docker run -Konfiguration bevorzugt.

Lokales Ausführen des Servers (ohne Docker)

Für die Entwicklung oder wenn Docker nicht bevorzugt wird, können Sie den Server direkt mit Python ausführen.

Voraussetzungen

1. Python-Umgebung: Stellen Sie sicher, dass Sie Python 3.9+ haben und die Abhängigkeiten aus requirements.txt installiert haben.
2. .env -Datei: Die .env Datei muss im Projektstammverzeichnis ( /Users/username/mcp_servers/ISE_MCP/.env ) vorhanden sein.

Ausführung

Navigieren Sie zum Stammverzeichnis des Projekts und führen Sie Folgendes aus:

Standardmäßig ist src/ise_mcp_server/server.py so konfiguriert, dass der Server über streamable-http gestartet wird, das normalerweise unter http://127.0.0.1:8000/mcp verfügbar ist. Sie können server.py anpassen, um den Transport (z. B. auf stdio ) oder andere Serverparameter zu ändern, falls dies für Ihren spezifischen Client erforderlich ist.

Entwicklung und Tests mit MCP Inspector (Lokales Python)

Für die lokale Entwicklung mit dem MCP Inspector:

Nach dem Ausführen dieses Befehls wird der MCP Inspector gestartet.

• Für STDIO-Tests mit Inspector:
  1. Wählen Sie im Inspector als Transporttyp „STDIO“ aus.
  2. Legen Sie den Befehl zum Ausführen des Servers als python src/ise_mcp_server/server.py fest.
  3. Stellen Sie eine Verbindung zum Server her.
• Für HTTP-Tests mit Inspector:
  1. Führen Sie python src/ise_mcp_server/server.py in einem separaten Terminal aus, um den Server zu starten (standardmäßig wird streamable-http verwendet).
  2. Wählen Sie im MCP-Inspektor „HTTP“ aus.
  3. Legen Sie die URL auf http://127.0.0.1:8000/mcp (oder Ihren konfigurierten Endpunkt) fest.
  4. Stellen Sie eine Verbindung zum Server her.

Lokale Ausführung mit uv und fastmcp run (Alternative für STDIO)

Wenn Sie uv und fastmcp global oder in Ihrer Umgebung installiert haben, können Sie den Server auch mit dem Befehl fastmcp run ausführen, was häufig für STDIO-basierte Clients nützlich ist.

Voraussetzungen:

1. uv installiert und in Ihrem PATH.
2. fastmcp ist in der uv verwendeten Umgebung (oder global) installiert.
3. .env -Datei im Projektstamm vorhanden.

Ausführung:

Dieser Befehl weist uv an, fastmcp run src/ise_mcp_server/server.py --transport stdio im angegebenen Projektverzeichnis auszuführen. Das Flag --transport stdio ist wichtig für Clients, die STDIO erwarten.

Claude Desktop-Konfiguration für uv Methode: Wenn Sie diese Methode für Claude Desktop bevorzugen, können Sie sie wie folgt konfigurieren:

Diese Konfiguration wird von Claude Desktop übernommen, wenn Sie Ihren Server „ISE_LOCAL_UV“ nennen oder den Schlüssel entsprechend anpassen. Beachten Sie, dass fastmcp run die .env Datei automatisch aus dem aktuellen Arbeitsverzeichnis (in diesem Fall /Users/username/mcp_servers/ISE_MCP ) lädt.

Interaktion mit dem Server

Sobald der ISE MCP-Server ausgeführt wird, kann mit jedem MCP-kompatiblen Client (z. B. MCP Inspector) darauf zugegriffen werden.

Werkzeugerkennung

Clients können verfügbare Tools entdecken. Jedes Tool entspricht einem Eintrag in urls.json . Toolnamen werden aus dem Feld „ Name “ abgeleitet (z. B. wird aus „Identity Groups“ identity_groups ).

Aufrufen eines Tools

Tools werden mit einem einzigen optionalen Argument, params , aufgerufen, das eine Instanz eines Pydantic-Modells ( FilterableToolInput oder NonFilterableToolInput ) ist.

Beispiel: Aufrufen des endpoints Tools ohne Filter: Ein MCP-Client würde normalerweise den Aufruf des Tools ohne explizite Argumente zulassen, wenn das Eingabemodell des Tools default_factory verwendet.

Beispiel: Aufruf des endpoints Tools mit Filtern: Die Argumente würden gemäß dem Pydantic-Modell strukturiert. Für ein Tool, das von einem Endpunkt mit FilterableFields generiert wird:

• filter_expression (Zeichenfolge, optional): Gibt Filter im Format fieldName.OPERATION.value an (z. B. mac.EQUALS.AA:BB:CC:DD:EE:FF ). Informationen zu verfügbaren FilterableFields und unterstützten ISE-Operationen (z. B. CONTAINS, EQUALS, STARTSWITH) finden Sie in der Dokumentation des Tools.
• query_params (dict, optional): Ermöglicht die Angabe beliebiger Abfrageparameter (z. B. {"size": 100, "page": 2} ). Diese werden direkt an die ISE-API übergeben.

Wenn ein Endpunkt in urls.json ein leeres FilterableFields Array hat, akzeptiert das entsprechende Tool nur query_params .

Spezifische Einzelheiten zu den Endpunkten und verfügbaren filterbaren Feldern finden Sie in der dynamisch generierten Dokumentationszeichenfolge der einzelnen Tools.

Protokollierung

Der Server verwendet das Standard-Python- logging , das von fastmcp konfiguriert wird. Protokollmeldungen zu Servervorgängen und API-Interaktionen werden in der Konsole ausgegeben.

Lizenz

Apache 2.0-Lizenz