AsusWRT MCP Server

Servidor MCP de AsusWRT

mcp-name: io.github.teefloo/asuswrt-mcp

Servidor del Model Context Protocol (MCP) para la administración segura y controlada de routers AsusWRT y AsusWRT-Merlin a través de SSH.

Resumen

Este servidor MCP proporciona a los asistentes de IA (como Claude, Cursor, etc.) una interfaz segura para monitorear y administrar routers AsusWRT. Opera exclusivamente a través de SSH utilizando operaciones en lista blanca: sin ejecución de comandos arbitrarios, sin modificaciones de firmware y sin restablecimientos de fábrica.

Características

Monitoreo de Solo Lectura (42 herramientas)

Categoría	Herramientas
Identidad y Salud	Modelo del router, versión de firmware, tiempo de actividad, carga, memoria
Red	Detalles de LAN/WAN, configuración de DNS, estado de IPv6, tabla de enrutamiento
Clientes	Clientes conectados, concesiones DHCP, vecinos ARP
Inalámbrico	Estado de radio, SSIDs, redes de invitados, conteo de clientes por banda
Servicios	Procesos en ejecución, puertos abiertos, trabajos cron
Almacenamiento	Dispositivos USB, montajes, particiones, uso del sistema de archivos
Seguridad	UPnP, DDNS, estado de Samba, uso de conntrack
VPN	Servidor OpenVPN, WireGuard, perfiles de cliente VPN
Administración	Puertos de administración web, configuración de acceso SSH/telnet
Diagnósticos	Diagnósticos SSH TCP/banner/auth, instantánea de configuración

Herramientas de Mutación (con protecciones de seguridad)

Todas las herramientas de mutación requieren:

• Parámetro confirm: true
• Variable de entorno ASUSWRT_ALLOW_MUTATIONS=true
• Soporte para dry_run: true para previsualizar cambios

Herramienta	Descripción
asuswrt_restart_service	Reiniciar servicios en lista blanca (httpd, firewall, wireless, dnsmasq, etc.)
asuswrt_dhcp_server	Habilitar/deshabilitar servidor DHCP
asuswrt_upnp	Habilitar/deshabilitar UPnP
asuswrt_radio	Habilitar/deshabilitar bandas de radio Wi-Fi
asuswrt_guest_wifi	Habilitar/deshabilitar Wi-Fi de invitados
asuswrt_guest_lan_access	Alternar acceso LAN para Wi-Fi de invitados
asuswrt_port_forwarding	Listar, agregar, eliminar, habilitar/deshabilitar reglas de reenvío de puertos
asuswrt_vpn_server	Habilitar/deshabilitar servidor OpenVPN
asuswrt_parental_access	Listar, bloquear, desbloquear, eliminar reglas de control parental
asuswrt_parental_block_all	Alternar modo de bloqueo total
asuswrt_dhcp_reservation	Listar, agregar, eliminar reservas estáticas DHCP

Modelo de Seguridad

• Sin SSH arbitrario: Solo se ejecutan comandos en lista blanca mediante llamadas NVRAM y de servicio
• Sin operaciones de firmware: Sin acceso a flash, restablecimiento o bootloader
• Redacción de secretos: Las contraseñas y datos sensibles nunca se exponen en las respuestas de las herramientas
• Soporte de simulación: Cada mutación se puede previsualizar antes de aplicarse
• Confirmación requerida: Las mutaciones requieren confirm=True explícito
• Transporte solo SSH: Sin exposición de la API web del router

Requisitos previos

• Python 3.11+
• Un router AsusWRT o AsusWRT-Merlin con acceso SSH habilitado
• Conectividad de red desde el cliente MCP al router

Instalación

1. Clonar y configurar

git clone https://github.com/Teeflo/asuswrt-mcp.git
cd asuswrt-mcp

# Create virtual environment
python -m venv .venv

# Activate (Linux/macOS)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

# Install dependencies
pip install -e .

2. Configurar el entorno

# Copy example configuration
cp .env.example .env

# Edit with your router credentials
# Use your favorite editor:
notepad .env        # Windows
nano .env           # Linux/macOS

3. Configurar .env

# Required: Router connection
ASUSWRT_HOST=192.168.1.1
ASUSWRT_SSH_USERNAME=admin
ASUSWRT_SSH_PASSWORD=your_password

# Optional: SSH key authentication
# ASUSWRT_SSH_KEY_FILE=~/.ssh/id_rsa

# Optional: Enable mutations (disabled by default)
# ASUSWRT_ALLOW_MUTATIONS=true

# Optional: Connection settings
# ASUSWRT_SSH_PORT=22
# ASUSWRT_TIMEOUT_SECONDS=10

Uso

Ejecutar el servidor MCP

# Standard stdio mode
python -m asuswrt_mcp.server

# Or use the entry point
asuswrt-mcp

Configurar en Claude Desktop / Cursor

Agregue a su claude_desktop_config.json:

{
  "mcpServers": {
    "asuswrt-mcp": {
      "command": "C:\\path\\to\\asuswrt-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "asuswrt_mcp.server"],
      "env": {
        "ASUSWRT_HOST": "192.168.1.1",
        "ASUSWRT_SSH_USERNAME": "admin",
        "ASUSWRT_SSH_PASSWORD": "your_password"
      }
    }
  }
}

Uso con npx Inspector (desarrollo)

npx @modelcontextprotocol/inspector python -m asuswrt_mcp.server

Desarrollo

Ejecutar pruebas

pip install -e ".[dev]"
pytest

Ejecutar con pruebas de integración de router en vivo

ASUSWRT_TEST_ROUTER=1 pytest

Estructura del Proyecto

asuswrt-mcp/
├── src/asuswrt_mcp/
│   ├── server.py          # FastMCP entrypoint & tool definitions
│   ├── service.py         # Business logic & router operations
│   ├── config.py          # Settings management
│   ├── clients/
│   │   └── ssh.py         # SSH client wrapper
│   ├── nvram.py           # NVRAM parsing utilities
│   ├── ssh_parsers.py     # Output parsers for SSH commands
│   ├── security.py        # Mutation guards & redaction
│   ├── validators.py      # Input validation
│   ├── responses.py       # Tool response formatting
│   ├── errors.py          # Custom exceptions
│   └── serialization.py   # Safe serialization
├── tests/                 # Test suite (69 tests)
├── .env.example           # Example configuration
├── pyproject.toml         # Project metadata
└── README.md              # This file

Licencia

Licencia MIT: consulte LICENSE para más detalles.

Agradecimientos

• asusrouter por la biblioteca Python subyacente
• MCP por la especificación del protocolo
• AsusWRT-Merlin por el firmware