OpenWRT-MCP

OpenWRT-MCP

Servidor MCP (Model Context Protocol) de solo lectura para la gestión y diagnóstico de routers OpenWRT. Permite que asistentes de IA (Claude Desktop, LibreChat, Cline) observen y analicen un router OpenWRT sin ningún tipo de acceso de escritura.

Requisitos

• Python 3.14+ (para uso local) o Docker
• Router OpenWRT con SSH habilitado (Dropbear u OpenSSH)
• Par de claves SSH para autenticación

Inicio rápido

1. Generar clave SSH

ssh-keygen -t ed25519 -f openwrt_id_ed25519 -C "openwrt-mcp"
ssh-copy-id -i openwrt_id_ed25519.pub root@192.168.0.1

2. Configurar

cp .env.example .env
# Edit .env with your OPENWRT_HOST and SSH key path

3. Ejecutar con Docker

Opción A — con docker compose:

# After editing .env, for Docker add MCP_UNSAFE_PUBLIC_ACCESS_CONFIRMED=1 to .env
docker compose up -d

Opción B — con docker run simple:

docker run -d \
  --name openwrt-mcp \
  -p 9094:9094 \
  -p 9095:9095 \
  -p 9096:9096 \
  -e OPENWRT_HOST=192.168.0.1 \
  -e OPENWRT_SSH_KEY=/app/keys/openwrt_id_ed25519 \
  -e MCP_UNSAFE_PUBLIC_ACCESS_CONFIRMED=1 \
  -v $(pwd)/keys:/app/keys:ro \
  ghcr.io/paulomac1000/openwrt-mcp:latest

Compilación local:

git clone https://github.com/paulomac1000/openwrt-mcp.git
cd openwrt-mcp
docker build -t openwrt-mcp .
# Then run with the same docker run command above

4. Ejecutar localmente (Python 3.14+)

pip install -e ".[dev]"
OPENWRT_HOST=192.168.0.1 OPENWRT_SSH_KEY=/path/to/key openwrt-mcp

Puertos

Puerto	Protocolo	Propósito	Endpoint
9094	HTTP	Verificación de salud	GET /health
9095	SSE	Transporte MCP (SSE)	/sse, /messages
9096	HTTP	API REST	/api/*

Verificar

# Health check
curl http://localhost:9094/health

# List all MCP tools
curl http://localhost:9096/api/tools

# Call a tool
curl -X POST http://localhost:9096/api/tools/get_router_info \
  -H "Content-Type: application/json" \
  -d '{}'

# Get tool manifest
curl http://localhost:9096/api/tools/get_router_info/manifest

Herramientas disponibles (24)

Las herramientas se clasifican por nivel de riesgo: las herramientas [READ] son seguras — consultan el router sin efectos secundarios. Las herramientas [WRITE] pueden modificar el estado del router y requieren ENABLE_WRITE_OPERATIONS=1 en .env. Las herramientas [DESTRUCTIVE] son irreversibles (reinicio) y requieren confirmación explícita.

Categoría	Herramienta	Riesgo	Descripción
Conexión	test_router_connection	READ	Verificar conectividad SSH
Sistema	get_router_info	READ	Información de placa, memoria, tiempo de actividad, versión
	get_router_context	READ	Instantánea de contexto unificada (sistema, wifi, DHCP, salud)
	describe_router_capabilities	READ	Introspección del servidor — herramientas, manifiestos, recopiladores
Red	get_router_wifi_status	READ	Radios WiFi, SSID, clientes conectados
	get_router_dhcp_leases	READ	Concesiones DHCP activas
	diagnose_router_connectivity	READ	Pruebas de ping, DNS y puerta de enlace
	ping_host	READ	Hacer ping a un host específico
	traceroute_host	READ	Traceroute a un host
	nslookup_host	READ	Consulta DNS desde el router
	wifi_scan	READ	Escanear redes WiFi vecinas
Seguridad	get_router_firewall_rules	READ	Reglas de iptables / nftables / fw4
	read_router_uci_config	READ	Leer secciones de configuración UCI
Diagnóstico	get_router_logs	READ	Registros del sistema recientes
	search_router_logs	READ	Búsqueda de registros filtrada
Paquetes	list_router_packages	READ	Paquetes OPKG instalados
DHCP	get_dhcp_static_leases	READ	Reservas DHCP estáticas
	search_dhcp_logs	READ	Buscar eventos DHCP en registros
	get_device_dhcp_details	READ	Información completa del dispositivo (concesión, reserva, registros)
Escritura	uci_set	WRITE	Establecer un valor de configuración UCI
	uci_commit	WRITE	Confirmar cambios UCI permanentemente
	restart_interface	WRITE	Reiniciar una interfaz de red
	reload_network	WRITE	Recargar servicios de red
	reboot_device	DESTRUCTIVE	Reiniciar el router (irreversible)

Configuración

Toda la configuración se realiza mediante variables de entorno. Consulte .env.example para ver una plantilla completa.

Obligatorias

Variable	Descripción	Ejemplo
OPENWRT_HOST	Dirección IP del router	192.168.0.1
OPENWRT_SSH_KEY	Ruta a la clave privada SSH	/app/keys/openwrt_id_ed25519

Opcionales

Variable	Predeterminado	Descripción
OPENWRT_PORT	22	Puerto SSH
OPENWRT_USER	root	Usuario SSH
MCP_SSE_PORT	9095	Puerto de transporte SSE MCP
REST_API_PORT	9096	Puerto de API REST
HEALTH_PORT	9094	Puerto de verificación de salud
SSH_TIMEOUT	30	Tiempo de espera de conexión SSH (segundos)
MCP_UNSAFE_PUBLIC_ACCESS_CONFIRMED	—	Establecer en 1 para reenvío de puertos Docker
ENABLE_WRITE_OPERATIONS	false	Establecer en 1 para habilitar herramientas de escritura (uci_set, reboot y otras)
OPENWRT_PASSWORD	None	Contraseña SSH (no recomendado — usar claves SSH)
ENABLE_AUDIT_LOGGING	true	Registrar todos los comandos ejecutados
AUDIT_LOG_FILE	/app/log/openwrt_mcp.log	Ruta del registro de auditoría
LOG_LEVEL	INFO	Nivel de registro
OPENWRT_KNOWN_HOSTS	—	Ruta al archivo known_hosts de SSH para verificación de clave de host

Modelo de seguridad

• Solo lectura por defecto — Todos los comandos SSH están en lista blanca; las operaciones de escritura (uci set, ifdown, ubus reboot) requieren ENABLE_WRITE_OPERATIONS=1
• Lista blanca de comandos — Patrones de solo lectura explícitos (ubus call, uci show, cat /proc/*, logread, ping y otros)
• Lista blanca de comandos de escritura — Ruta execute_write() separada para operaciones de escritura (ifdown, ifup, uci set/commit, /etc/init.d/network, ubus reboot)
• Patrones bloqueados — rm, reboot, wget, curl, uci set (en ruta de lectura), metacaracteres de shell (;, |, &&, $ y otros)
• Autenticación basada en claves — Se desaconseja el inicio de sesión con contraseña
• Verificación de clave de host SSH — Opcional mediante OPENWRT_KNOWN_HOSTS (establecer la ruta del archivo known_hosts)
• Registro de auditoría — Todos los comandos se registran con marcas de tiempo para responsabilidad
• Enlace a localhost — Todos los puertos se enlazan a 127.0.0.1 por defecto; establecer MCP_UNSAFE_PUBLIC_ACCESS_CONFIRMED=1 para Docker

Cumplimiento de estándares

Este servidor sigue dos estándares AI-First:

Estándar	Documento	Versión	Descripción
AFDS	docs_standards.md	v1.0	Estructura de documentación, esquema de frontmatter, lenguaje controlado
MCP Core	mcp-server-standards.md	v1.1.0	Diseño de herramientas, contratos de respuesta, jerarquía de pruebas, seguridad

Nivel de cumplimiento: L3-ready (todas las reglas L1-L3 cumplidas; Matriz de consistencia de riesgos aplicada mediante pruebas automatizadas).

Pruebas

pip install -e ".[dev]"
pytest tests/unit/ tests/integration/ -q       # 268 tests (requires .env for integration)
pytest tests/unit/ --cov=openwrt_mcp -q         # 80%+ coverage
ruff check . && ruff format --check .           # lint
mypy src/openwrt_mcp/ --strict                  # type check
bandit -r src/openwrt_mcp/ -ll                  # security

Referencia rápida

Métrica	Valor
Python	3.14+ (Docker: 3.14)
Herramientas	24 (19 READ + 4 WRITE + 1 DESTRUCTIVE)
Pruebas	296 (215 unitarias + 53 de integración + 10 smoke + 18 e2e)
Cobertura	86%
Lint	0 errores (ruff + mypy --strict + bandit)
Docker	ghcr.io/paulomac1000/openwrt-mcp:latest
Estándares	AFDS v1.0 + MCP Core v1.1.0 — L2+
Licencia	MIT

Licencia

MIT