Servidor MCP de red

Un servidor del Protocolo de Contexto de Modelo (MCP) que permite a un agente de IA interactuar con un dispositivo de red Cisco IOS-XE a través de SSH. Creado en Python con FastMCP y Netmiko.

El servidor expone 7 herramientas (5 de lectura + 2 de escritura), cada una con una validación de entrada estricta y descripciones claras para que un agente LLM pueda descubrirlas y utilizarlas de forma autónoma.

Curso: Agente IA y Automatización — Sheridan College Autor: Ahmed Instructor: Sebastian

Tabla de contenidos

1. Entorno de laboratorio

2. Instalación

3. Ejecutar el servidor

4. Herramientas

5. Conectar a Claude Desktop

6. Ejemplos de interacciones

7. Permisos requeridos

8. Notas de seguridad

9. Solución de problemas

Entorno de laboratorio

Este proyecto está dirigido al Always-On IOS-XE DevNet Sandbox de Cisco. Es gratuito, accesible públicamente, no requiere reserva y siempre está activo.

Referencia: Cisco DevNet — Always-On Sandboxes.

Comprobación rápida de conectividad desde su máquina:

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

Debería llegar al prompt Router# (o similar). Si esto funciona, el servidor MCP también funcionará.

El sandbox es compartido. Por favor, mantenga los cambios pequeños y no disruptivos (p. ej., solo edite descripciones de interfaces, no apague interfaces ni cambie IPs).

Instalación

Requiere 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

Dependencias:

• mcp[cli] — SDK de Python para MCP (proporciona FastMCP)

• netmiko — biblioteca SSH/CLI multi-proveedor

• python-dotenv — carga .env para desarrollo local

Ejecutar el servidor

Opción A — independiente (para pruebas locales)

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

python server.py

El servidor se ejecuta sobre stdio, por lo que espera mensajes JSON-RPC de MCP en stdin. En la práctica, no lo invocará manualmente; conectará Claude Desktop (ver más abajo) o la CLI de desarrollo mcp.

Opción B — inspector de desarrollo interactivo

mcp dev server.py

Esto abre el Inspector MCP en su navegador, donde puede listar herramientas y llamarlas manualmente.

Herramientas

Herramientas de lectura

Herramientas de escritura

Todas las salidas de las herramientas son cadenas JSON para que el LLM pueda razonar sobre datos estructurados. Cuando los analizadores TextFSM de Netmiko no pueden manejar una salida, el servidor recurre a texto CLI sin procesar dentro de un contenedor {"raw": "..."}.

Conectar a Claude Desktop

1. Localice el archivo de configuración de 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. Combine el bloque de abajo en el archivo (use la ruta absoluta completa a su 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"
      }
    }
  }
}

Una versión lista para copiar se encuentra en claude_desktop_config.example.json.

3. Cierre completamente y vuelva a abrir Claude Desktop. (Cerrar la ventana no es suficiente; mantiene el proceso MCP activo).

4. En un chat nuevo, haga clic en el icono 🛠️ / herramientas. Debería ver network-mcp-server listado con 7 herramientas.

Ejemplos de interacciones

Una vez conectado, pruebe estos prompts:

"¿A qué dispositivo estoy conectado? Dame su nombre de host, modelo y versión de IOS." El agente llamará a get_device_info.

"Lista todas las interfaces que actualmente tienen una dirección IP asignada." El agente llamará a get_interfaces y filtrará los resultados.

"Muéstrame la ruta por defecto." El agente llamará a get_routes y elegirá la entrada con la red 0.0.0.0.

"Establece la descripción en GigabitEthernet2 a 'gestionado por demo MCP', luego confirma que el cambio se aplicó." El agente llamará a configure_interface_description, luego (opcionalmente) a get_running_config con section='interface GigabitEthernet2' para verificar.

"Guarda la configuración en ejecución en la de inicio." El agente llamará a save_config.

Permisos requeridos

El servidor MCP necesita:

1. Salida de red desde la máquina host al puerto SSH del dispositivo (TCP/22 por defecto). En redes corporativas, puede necesitar una VPN o proxy.

2. Una cuenta de dispositivo con derechos de ejecución privilegiada — la cuenta admin del sandbox de DevNet ya tiene nivel enable. Si usa su propio dispositivo, la cuenta debe poder entrar en config t y ejecutar write memory.

3. Acceso de lectura local al archivo .env o variables de entorno equivalentes configuradas por Claude Desktop.

El servidor no necesita privilegios de root/admin en su estación de trabajo.

Notas de seguridad

• Las credenciales nunca están codificadas. Provienen de variables de entorno (DEVICE_USERNAME, DEVICE_PASSWORD). Si falta alguna variable de entorno requerida, el servidor se niega a conectar y devuelve un error claro.

• .env está ignorado por git. Se proporciona un .env.example (con valores de sandbox de DevNet seguros para compartir) en su lugar.

• Validación de entrada en cada herramienta. Los nombres de interfaz, descripciones y filtros de sección de configuración son validados mediante regex antes de llegar a la CLI del dispositivo. Los metacaracteres de shell (;, |, backtick, nueva línea, byte nulo) son rechazados.

• Las credenciales nunca se exponen como argumentos de herramientas. El LLM no puede leerlas, registrarlas ni exfiltrarlas; solo ve las salidas de las herramientas.

• Las herramientas de escritura incluyen verificación. configure_interface_description lee la configuración de vuelta después de aplicar el cambio e informa applied: true/false.

• El alcance es limitado. Las dos herramientas de escritura solo pueden cambiar descripciones de interfaces y guardar la configuración. Las operaciones destructivas (apagado, cambio de dirección IP, eliminación de VLAN, erase startup-config) están deliberadamente no expuestas.

Solución de problemas

"Missing required environment variable(s)" Olvidó configurar DEVICE_HOST / DEVICE_USERNAME / DEVICE_PASSWORD. Copie .env.example a .env o configúrelos en el bloque env de Claude Desktop.

"Authentication to failed" Verifique la contraseña. Si cambió el sandbox o usa un dispositivo diferente, asegúrese de que SSH esté habilitado y la cuenta tenga acceso de ejecución privilegiada.

"Connection to timed out" La salida de red está bloqueada. Intente ssh admin@sandbox-iosxe-latest-1.cisco.com desde la misma máquina. Si eso también se queda colgado, su firewall/VPN es el problema.

Claude Desktop no muestra el servidor después de editar la configuración Cierre completamente Claude Desktop (no solo cierre la ventana) y vuelva a abrirlo. En macOS: Cmd+Q. En Windows: clic derecho en el icono de la bandeja → Salir.

La llamada a la herramienta devuelve texto sin procesar en lugar de JSON analizado Esto significa que la plantilla TextFSM de Netmiko no coincidió con la salida del dispositivo (versión de IOS diferente, plataforma diferente). El servidor recurre a texto CLI sin procesar en {"raw": "..."}. El agente aún puede razonar sobre él; simplemente no está estructurado.