Nokia / Airtel GPON Home Router API & Web Dashboard

Controla, automatiza y gestiona tu Nokia G-2425G-A GPON Home Gateway (desplegado comúnmente por Airtel Xstream Fiber y otros ISP) mediante Web Dashboard, MCP (Model Context Protocol), REST API y CLI, con apodos de dispositivos persistentes (SQLite) y cero automatización de navegador.

💡 ¿Por qué este proyecto?

El problema

La mayoría de los routers domésticos de fibra (como el Nokia GPON ONT de Airtel) no ofrecen una API oficial ni integración con ecosistemas de hogar inteligente. Siempre que quieras:

• Comprobar qué dispositivos están conectados actualmente a tu Wi-Fi,

• Asignar apodos amigables (p. ej. "Akanksha Phone", "Guestroom TV"),

• Bloquear el acceso a internet de un dispositivo específico (p. ej., gestionar el tiempo de pantalla de los niños),

• O automatizar reglas de red según la hora o el estado del hogar inteligente...

...te ves obligado a abrir manualmente un navegador, navegar por un portal web lento, escribir las credenciales y hacer clic a través de múltiples menús de configuración anidados.

Peor aún, como el portal web del router utiliza un complejo esquema de cifrado híbrido en el lado del cliente (RSA-1024 + AES-128-CBC mediante JavaScript SJCL personalizado), los scripts simples de curl o las peticiones HTTP estándar fallan. La mayoría de los desarrolladores recurren a una automatización de navegador pesada y frágil (como Selenium o Puppeteer).

La solución

Este proyecto realiza ingeniería inversa completa del handshake criptográfico RSA + AES del router en Python puro.

Se comunica directamente con los endpoints internos del router con tiempos de respuesta inferiores a un segundo y cero sobrecarga de navegador. Combina una base de datos SQLite local para almacenar metadatos persistentes de los dispositivos (apodos, notas personalizadas, primera/última vez visto) y envuelve ese motor central en cuatro interfaces listas para usar:

1. 🌐 Web Dashboard — Elegante aplicación web de glassmorphism oscuro con búsqueda en vivo, edición de apodos y alternancias de bloqueo/desbloqueo con 1 clic.

2. 🤖 MCP Server — Permite a los agentes de IA (como Antigravity, Claude, Cursor) controlar tu Wi-Fi y bloquear/desbloquear por apodos amigables.

3. ⚡ REST API (FastAPI) — Perfecta para Home Assistant, webhooks y automatización personalizada.

4. 🖥️ CLI — Comandos de terminal instantáneos y scripting de bash.

Related MCP server: tplink-mcp

🎯 Casos de uso reales

1. 🤖 Control por voz y chat con agentes de IA (vía MCP)

Conecta este proyecto a cualquier asistente de IA compatible con MCP (p. ej., Claude Desktop, Antigravity IDE, Cursor). Simplemente puedes decir:

"Establece un apodo 'Akanksha Phone' para el dispositivo f6:cf:28:1c:bd:e5."
"Bloquea Guestroom TV del acceso a internet."
"¿Está el televisor de la sala conectado al Wi-Fi ahora mismo?"
"Desbloquea Akanksha Phone."\

El agente de IA inspeccionará tus dispositivos conectados, resolverá el objetivo por apodo/nombre de host/IP/MAC y ejecutará la acción en tu router automáticamente.

2. 🌐 Panel web visual

Abre http://localhost:8000/ para monitorear todos los dispositivos conectados en una interfaz web responsive:

• Barra de estadísticas en vivo: Total de dispositivos, Activos en línea, cantidad de bloqueados y cantidad de apodos personalizados.

• Búsqueda y filtro instantáneos: Filtra por Todos, En línea, Bloqueados o Apodo personalizado.

• Editor de apodos integrado: Asigna apodos amigables y notas de ubicación a cualquier dispositivo.

• Bloqueo/desbloqueo con 1 clic: Alterna el acceso con indicadores de carga inmediatos y notificaciones toast.

3. 🏠 Integración con Home Assistant

Integra tu router en Home Assistant mediante la API REST:

• Automatizaciones de hora de dormir: Bloquea automáticamente las tabletas y consolas de juegos de los niños a las 10:00 PM en noches de colegio.

• Detección de presencia: Activa automatizaciones cuando teléfonos específicos se conectan o se desconectan de la red.

• Alternancias del panel: Crea botones de interruptor dedicados de "Bloquear / Desbloquear Internet" en tu panel de Home Assistant Lovelace.

✨ Características

• 🏷️ Apodos de dispositivos persistentes — Almacenados en SQLite (data/router.db) para que puedas referenciar dispositivos por nombres fáciles de recordar como "Guestroom TV".

• 🎯 Resolución inteligente de múltiples objetivos — Bloquear/desbloquear/consultar por apodo, nombre de host, dirección IP o dirección MAC (admite coincidencia parcial y sin distinción de mayúsculas/minúsculas).

• 🔍 Listar dispositivos conectados — Nombre de host, dirección IP, dirección MAC, estado activo en línea e interfaz de conexión (Ethernet, 2.4GHz 802.11, 5GHz 802.11ac).

• 🚫 Bloquear dispositivos — Bloquea el acceso a internet 24/7 para cualquier dispositivo mediante reglas de Control parental.

• ✅ Desbloquear dispositivos — Elimina las reglas de bloqueo al instante.

• 📋 Listar políticas bloqueadas — Ve todas las políticas de restricción de acceso y horarios activos.

• 🔄 Sesiones de auto-sincronización y autocuración — Re-inicio de sesión automático y recuperación de sesión si las sesiones del router expiran.

• 🔐 Cero sobrecarga de navegador — Autenticación criptográfica pura mediante pycryptodome y requests.

🏗️ Arquitectura: cuatro formas de interactuar

📦 Instalación

# Clone the repository
git clone https://github.com/surajnai567/airtel-router-api.git
cd airtel-router-api

# Install dependencies
pip install -r requirements.txt

Dependencias: requests, pycryptodome, python-dotenv, fastapi, uvicorn, mcp

⚙️ Configuración

Crea un archivo .env en el directorio raíz (o cópialo desde .env.example):

ROUTER_IP=192.168.1.1
ROUTER_USERNAME=admin
ROUTER_PASSWORD=your_router_password

# Optional: REST API & Dashboard settings
API_HOST=0.0.0.0
API_PORT=8000

🔒 Nota de seguridad: Los archivos .env y data/*.db están incluidos en .gitignore para que tus credenciales del router y la base de datos local nunca se confirmen.

🌐 1. Panel web y API REST

Inicia el servidor:

python -m api.server

• Abre http://localhost:8000/ en tu navegador para ver el Panel web.

• Abre http://localhost:8000/docs para ver la documentación interactiva de la API Swagger.

Endpoints REST

🤖 2. Uso del servidor MCP (para agentes de IA)

Expón las herramientas del router directamente a los agentes de IA utilizando el Model Context Protocol (MCP).

Herramientas MCP disponibles

• list_devices() — Devuelve una tabla formateada con Nickname, Hostname, IP, MAC, Active, Blocked e Interface.

• set_device_nickname(target, nickname, notes=None) — Establece o actualiza el apodo amigable de un dispositivo.

• block_device(target, policy_name=None) — Bloquea un dispositivo por apodo (p. ej. "Guestroom TV"), nombre de host, IP o MAC.

• unblock_device(target) — Desbloquea un dispositivo por apodo, nombre de host, IP o MAC.

• list_blocked_devices() — Devuelve los dispositivos bloqueados activos con sus apodos y políticas.

Configuración de MCP

Añade este servidor a la configuración de tu cliente MCP (p. ej. claude_desktop_config.json o mcp_config.json):

{
  "mcpServers": {
    "home_router": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "d:/project/routerapi"
    }
  }
}

🖥️ 3. Uso de la CLI

# List all connected/known devices (with nicknames)
python -m cli.main list

# List all currently blocked devices
python -m cli.main blocked

# Block a device by MAC address or Nickname
python -m cli.main block AA:BB:CC:DD:EE:FF

# Block a device with a custom policy name
python -m cli.main block AA:BB:CC:DD:EE:FF --name "Kid_Tablet_Block"

# Unblock a device by MAC address
python -m cli.main unblock AA:BB:CC:DD:EE:FF

🐍 4. Uso de la biblioteca de Python

from core import RouterAPI

# Initialize and authenticate
router = RouterAPI(ip_address="192.168.1.1", username="admin", password="admin_password")
if router.login():
    # 1. Set a friendly nickname
    router.set_nickname("f6:cf:28:1c:bd:e5", "Akanksha Phone")

    # 2. Get all devices (auto-synced with SQLite)
    devices = router.list_devices()
    for d in devices:
        print(f"[{'ONLINE' if d['active'] else 'OFFLINE'}] {d['nickname'] or d['hostname']} ({d['ip']}) - {d['mac']}")

    # 3. Block directly by nickname!
    router.block_device("Akanksha Phone")

    # 4. Unblock by nickname!
    router.unblock_device("Akanksha Phone")

    # Clean up session
    router.logout()

📁 Estructura del proyecto

routerapi/
├── core/                      # Core business logic (the engine)
│   ├── __init__.py            # Re-exports RouterAPI, DB helpers, and crypto
│   ├── client.py              # RouterAPI client class with smart target resolution
│   ├── crypto.py              # AES-CBC + RSA encryption implementation
│   └── db.py                  # SQLite database layer for persistent nicknames
│
├── api/                       # REST API & Web Dashboard
│   ├── __init__.py
│   ├── server.py              # FastAPI server with CORS, static routes, & models
│   └── static/                # Web Dashboard assets
│       ├── index.html         # Dashboard HTML template
│       ├── style.css          # Dark glassmorphism stylesheet
│       └── app.js             # Frontend state management & async API calls
│
├── mcp_server/                # Model Context Protocol interface
│   ├── __init__.py
│   └── server.py              # MCP server exposing router tools to AI
│
├── cli/                       # Terminal interface
│   ├── __init__.py
│   └── main.py                # Argparse CLI entry point
│
├── data/                      # Local SQLite storage (git-ignored)
│   └── router.db              # Persistent device metadata & nicknames
│
├── .env                       # Credentials (git-ignored)
├── .env.example               # Template environment configuration
├── .gitignore
├── requirements.txt           # Project dependencies
└── Readme.md                  # Project documentation

⚠️ Notas y aviso legal

• Caducidad de sesión y autocuración: Las sesiones del router caducan naturalmente tras la inactividad. Los servidores API y MCP gestionan automáticamente la re-autenticación en llamadas posteriores.

• Compatibilidad con Control parental: Admite tanto el firmware NUEVO (NPCProfileList, control de acceso basado en grupos) como el firmware ANTIGUO (pc_config, políticas de acceso).

• Hardware probado: Probado en Nokia G-2425G-A GPON Home Gateway (Airtel Xstream Fiber).

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para más detalles.