ISE MCP Server

Servidor ISE MCP (usando FastMCP)

Descripción general

El servidor MCP de ISE es un servidor de Protocolo de Contexto de Modelo (MCP) desarrollado con la biblioteca fastmcp de Python. Expone dinámicamente los endpoints de la API de Cisco Identity Services Engine (ISE) como herramientas MCP estructuradas y fáciles de detectar. Este servidor permite a los clientes interactuar con las API REST de Cisco ISE de forma estandarizada, ofreciendo funciones como la generación dinámica de herramientas y el filtrado de respuestas de la API.

Características

• Generación dinámica de herramientas: las herramientas MCP se crean automáticamente según las entradas en el archivo de configuración src/ise_mcp_server/urls.json .
• Integración con FastMCP: aprovecha la biblioteca fastmcp para una implementación sólida del servidor MCP, incluida la generación de esquemas y el manejo de solicitudes.
• Llamadas API asincrónicas: utiliza httpx.AsyncClient para comunicación sin bloqueo con Cisco ISE.
• Filtrado de API: admite el filtrado de resultados de API de Cisco ISE a través de argumentos filter_expression y query_params en cada herramienta.
• Configuración basada en el entorno: los detalles de conexión de Cisco ISE (URL base, nombre de usuario, contraseña) y la configuración de verificación SSL ( ISE_VERIFY_SSL ) se configuran mediante un archivo .env .
• Documentaciones detalladas: las herramientas generadas dinámicamente incluyen documentaciones completas que explican su propósito, el punto final de la API de ISE al que se dirigen y cómo usar los parámetros de filtrado.
• Interacción estandarizada: se adhiere al Protocolo de contexto del modelo, lo que permite la interacción a través de cualquier cliente compatible con MCP.
• Transporte HTTP transmitible: configurado para utilizar el transporte streamable-http de manera predeterminada para el acceso basado en web.

Configuración

Servidor

{ "mcpServers": { "ise": { "comando": "python", "args": [ "ise_mcp_server.py", "--oneshot" ], "env": { "ISE_BASE": " https://devnetsandboxise.cisco.com ", "NOMBRE DE USUARIO": "solo lectura", "CONTRASEÑA": "ISEisC00L" } } } }

Requisitos

• Python 3.9 o superior.
• Los paquetes de Python necesarios se listan en requirements.txt (en la raíz del proyecto). Instálelos usando:
  pip install -r requirements.txt
  O, si usas uv :
  uv pip install -r requirements.txt
  Las dependencias clave incluyen fastmcp , httpx , pydantic y python-dotenv . (Asegúrese de que requirements.txt refleje httpx en lugar de requests ).

Configuración

1. Variables de entorno: Cree un archivo .env en el directorio raíz del proyecto ( /Users/username/mcp_servers/ISE_MCP/.env ) con sus credenciales de API de Cisco ISE y la URL base:
   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. Configuración de URL ( urls.json ): Asegúrese de que el archivo src/ise_mcp_server/urls.json (ubicado en el mismo directorio que src/ise_mcp_server/server.py ) esté presente y correctamente estructurado. Este archivo define los puntos finales de la API de ISE que se expondrán como herramientas MCP.
   [ { "URL": "/ers/config/endpoint", "Name": "Endpoints", "FilterableFields": ["mac", "name", "description", "identityGroupName"] }, { "URL": "/ers/config/identitygroup", "Name": "Identity Groups", "FilterableFields": ["name", "description"] } // ... more endpoints ]
   • URL : la ruta relativa del punto final de la API de Cisco ISE.
   • Name : un nombre legible para humanos que se utiliza para derivar el nombre de la herramienta MCP (por ejemplo, "Puntos finales" se convierte en los endpoints de la herramienta).
   • FilterableFields : Una matriz de cadenas que enumera los campos conocidos que se pueden usar con filter_expression para este endpoint. Esta lista es mantenida por el usuario y es crucial para un filtrado eficaz.

Ejecución del servidor con Docker para Claude Desktop

Este servidor está diseñado para ejecutarse como un contenedor Docker, especialmente cuando se utiliza con clientes como Claude Desktop que interactúan a través de STDIO.

Prerrequisitos

1. Docker instalado: asegúrese de que Docker Desktop esté instalado y en ejecución.
2. Archivo .env : Su archivo .env (como se describe en Configuración) debe estar presente en la raíz del proyecto ( /Users/username/mcp_servers/ISE_MCP/.env ).
3. Archivo Docker configurado para STDIO: El Dockerfile de este proyecto ( Dockerfile ) debe configurarse para usar el transporte stdio . El ENTRYPOINT debería verse así:
   ENTRYPOINT ["python", "-m", "ise_mcp_server", "--transport", "stdio"]
   Asegúrese de no copiar el archivo .env .

Construir la imagen de Docker

Navegue hasta el directorio que contiene el Dockerfile ( /Users/username/mcp_servers/ISE_MCP/ ) y construya la imagen de Docker:

Alternativamente, si se construye desde la raíz del proyecto:

Configurar Claude Desktop

Actualice la configuración del servidor Claude Desktop MCP ( claude_desktop_config.json o cline_mcp_settings.json ) para el servidor "ISE_MCP" de la siguiente manera:

Explicación de los argumentos de Docker:

• run : ejecuta el contenedor Docker.
• -i : (Interactivo) Mantiene STDIN abierto incluso si no está conectado, lo cual es crucial para la comunicación MCP basada en STDIO.
• --rm : elimina automáticamente el contenedor cuando sale.
• --env-file : Especifica la ruta a su archivo .env en el equipo host. Docker cargará estas variables en el contenedor.
• ise-mcp:latest : el nombre y la etiqueta de la imagen de Docker que se ejecutará.
• cwd : establece el directorio de trabajo para el comando, garantizando que las rutas relativas (como para --env-file ) se resuelvan correctamente si Claude Desktop ejecuta comandos desde un directorio predeterminado diferente.

Ejecución con Docker Compose (alternativa para pruebas locales)

También se proporciona un archivo docker-compose.yml para pruebas locales. Este compila la imagen y ejecuta el contenedor, cargando las variables de entorno desde el archivo .env .

Este método es adecuado para pruebas directas, pero la configuración docker run anterior es la preferida para la integración de Claude Desktop.

Ejecutar el servidor localmente (sin Docker)

Para el desarrollo o cuando no se prefiere Docker, puede ejecutar el servidor directamente usando Python.

Prerrequisitos

1. Entorno de Python: asegúrese de tener Python 3.9+ y de haber instalado las dependencias de requirements.txt .
2. Archivo .env : el archivo .env debe estar presente en la raíz del proyecto ( /Users/username/mcp_servers/ISE_MCP/.env ).

Ejecución

Navegue al directorio raíz del proyecto y ejecute:

De forma predeterminada, src/ise_mcp_server/server.py está configurado para iniciar el servidor mediante el transporte streamable-http , normalmente disponible en http://127.0.0.1:8000/mcp . Puede modificar server.py para cambiar el transporte (por ejemplo, a stdio ) u otros parámetros del servidor si es necesario para su cliente específico.

Desarrollo y pruebas con MCP Inspector (Python local)

Para el desarrollo local con el Inspector MCP:

Después de ejecutar este comando, se iniciará el Inspector MCP.

• Para pruebas STDIO con Inspector:
  1. Seleccione “STDIO” como tipo de transporte en el Inspector.
  2. Establezca el comando para ejecutar el servidor como python src/ise_mcp_server/server.py .
  3. Conectarse al servidor.
• Para pruebas HTTP con Inspector:
  1. Ejecute python src/ise_mcp_server/server.py en una terminal separada para iniciar el servidor (utilizará streamable-http de manera predeterminada).
  2. En el Inspector de MCP, seleccione "HTTP".
  3. Establezca la URL en http://127.0.0.1:8000/mcp (o su punto final configurado).
  4. Conectarse al servidor.

Ejecución local con uv y fastmcp run (alternativa para STDIO)

Si tiene uv y fastmcp instalados globalmente o en su entorno, también puede ejecutar el servidor utilizando el comando fastmcp run , que suele ser útil para clientes basados en STDIO.

Prerrequisitos:

1. uv instalado y en su PATH.
2. fastmcp instalado en el entorno que utilizará uv (o globalmente).
3. Archivo .env presente en la raíz del proyecto.

Ejecución:

Este comando indica uv que ejecute fastmcp run src/ise_mcp_server/server.py --transport stdio dentro del directorio del proyecto especificado. El indicador --transport stdio es importante para los clientes que esperan STDIO.

Configuración de Claude Desktop para el método uv : Si prefiere este método para Claude Desktop, puede configurarlo de la siguiente manera:

Claude Desktop adoptará esta configuración si asigna el nombre "ISE_LOCAL_UV" a su servidor o ajusta la clave según corresponda. Tenga en cuenta que fastmcp run cargará automáticamente el archivo .env desde el directorio de trabajo actual ( /Users/username/mcp_servers/ISE_MCP en este caso).

Interactuar con el servidor

Una vez en ejecución, se puede acceder al servidor ISE MCP mediante cualquier cliente compatible con MCP (por ejemplo, MCP Inspector).

Descubrimiento de herramientas

Los clientes pueden descubrir las herramientas disponibles. Cada herramienta corresponde a una entrada en urls.json . Los nombres de las herramientas se derivan del campo Name (p. ej., "Grupos de identidad" se convierte en identity_groups ).

Llamar a una herramienta

Las herramientas se llaman con un único argumento opcional, params , que es una instancia de un modelo de Pydantic ( FilterableToolInput o NonFilterableToolInput ).

Ejemplo: llamar a la herramienta endpoints sin filtros: un cliente MCP normalmente permitiría llamar a la herramienta sin argumentos explícitos si el modelo de entrada de la herramienta usa default_factory .

Ejemplo: Llamada a la herramienta endpoints con filtros: Los argumentos se estructurarían según el modelo de Pydantic. Para una herramienta generada a partir de un punto final con FilterableFields :

• filter_expression (cadena, opcional): Especifica filtros con el formato fieldName.OPERATION.value (p. ej., mac.EQUALS.AA:BB:CC:DD:EE:FF ). Consulte la documentación de la herramienta para conocer FilterableFields disponibles y las operaciones ISE compatibles (p. ej., CONTAINS, EQUALS, STARTSWITH).
• query_params (dict, opcional): Permite especificar otros parámetros de consulta arbitrarios (p. ej., {"size": 100, "page": 2} ). Estos se pasan directamente a la API de ISE.

Si un punto final en urls.json tiene una matriz FilterableFields vacía, la herramienta correspondiente solo aceptará query_params .

Consulte la cadena de documentación generada dinámicamente de cada herramienta para obtener detalles específicos sobre su punto final y los campos filtrables disponibles.

Explotación florestal

El servidor utiliza el módulo logging estándar de Python, configurado por fastmcp . Los mensajes de registro relacionados con las operaciones del servidor y las interacciones con la API se mostrarán en la consola.

Licencia

Licencia Apache 2.0