Nokia / Airtel GPON Home Router API & Web Dashboard

Steuern, automatisieren und verwalten Sie Ihr Nokia G-2425G-A GPON Home Gateway (häufig von Airtel Xstream Fiber und anderen ISPs eingesetzt) über Web-Dashboard, MCP (Model Context Protocol), REST-API und CLI – mit dauerhaften Geräte-Spitznamen (SQLite) und ohne Browser-Automatisierung!

💡 Warum dieses Projekt?

Das Problem

Die meisten Heimfaser-Router (wie Airtels Nokia GPON ONT) bieten keine offizielle API oder Integration für Smart-Home-Ökosysteme. Immer wenn Sie:

• prüfen möchten, welche Geräte gerade mit Ihrem Wi-Fi verbunden sind,

• freundliche Spitznamen vergeben möchten (z. B. „Akanksha Phone", „Gästezimmer-TV"),

• den Internetzugriff für ein bestimmtes Gerät blockieren möchten (z. B. zur Verwaltung der Bildschirmzeit von Kindern),

• oder Netzwerkregeln basierend auf Zeit oder Smart-Home-Zuständen automatisieren möchten...

...sind Sie gezwungen, manuell einen Browser zu öffnen, ein träges Webportal zu navigieren, Anmeldedaten einzugeben und sich durch mehrere verschachtelte Einstellungsmenüs zu klicken.

Schlimmer noch: Da das Webportal des Routers ein komplexes clientseitiges Hybrid-Verschlüsselungsschema (RSA-1024 + AES-128-CBC über benutzerdefiniertes SJCL-JavaScript) verwendet, schlagen einfache curl-Skripte oder Standard-HTTP-Anfragen fehl. Die meisten Entwickler greifen auf schwere, fragile Browser-Automatisierung (wie Selenium oder Puppeteer) zurück.

Die Lösung

Dieses Projekt hat den RSA + AES-Kryptografie-Handshake des Routers vollständig in reinem Python reverse-engineered.

Es kommuniziert direkt mit den internen Endpunkten des Routers mit Antwortzeiten unter einer Sekunde und ohne Browser-Overhead. Es kombiniert eine lokale SQLite-Datenbank zur Speicherung dauerhafter Gerätemetadaten (Spitznamen, benutzerdefinierte Notizen, erstes/letztes Gesehen) und verpackt diese Kern-Engine in vier einsatzbereite Schnittstellen:

1. 🌐 Web-Dashboard – Elegante Web-App im dunklen Glassmorphism-Stil mit Live-Suche, Spitznamen-Bearbeitung und 1-Klick-Blockieren/Freigeben-Schaltern.

2. 🤖 MCP-Server – Ermöglicht KI-Agenten (wie Antigravity, Claude, Cursor) die Steuerung Ihres Wi-Fi und das Blockieren/Freigeben über freundliche Spitznamen.

3. ⚡ REST-API (FastAPI) – Perfekt für Home Assistant, Webhooks und benutzerdefinierte Automatisierung.

4. 🖥️ CLI – Sofortige Terminalbefehle und Bash-Skripting.

Related MCP server: OpenWRT SSH MCP Server

🎯 Praxisnahe Anwendungsfälle

1. 🤖 KI-Agent-Sprach- und Chatsteuerung (über MCP)

Verbinden Sie dieses Projekt mit jedem MCP-kompatiblen KI-Assistenten (z. B. Claude Desktop, Antigravity IDE, Cursor). Sie können einfach sagen:

„Setze einen Spitznamen ‚Akanksha Phone' für Gerät f6:cf:28:1c:bd:e5."
„Blockiere Gästezimmer-TV vom Internetzugriff."
„Ist der Wohnzimmer-TV gerade mit dem Wi-Fi verbunden?"
„Gib Akanksha Phone wieder frei."

Der KI-Agent prüft Ihre verbundenen Geräte, löst das Ziel über Spitzname/Hostname/IP/MAC auf und führt die Aktion automatisch auf Ihrem Router aus.

2. 🌐 Visuelles Web-Dashboard

Öffnen Sie http://localhost:8000/, um alle verbundenen Geräte in einer responsiven Web-UI zu überwachen:

• Live-Statistikleiste: Gesamtgeräte, aktive Online-Geräte, blockierte Anzahl und Anzahl benutzerdefinierter Spitznamen.

• Sofortsuche & Filter: Filtern nach Alle, Online, Blockiert oder Benutzerdefinierter Spitzname.

• Inline-Spitznamen-Editor: Vergeben Sie freundliche Spitznamen und Standortnotizen für jedes Gerät.

• 1-Klick-Blockieren/Freigeben: Zugriff mit sofortigen Lade-Spinnern und Toast-Benachrichtigungen umschalten.

3. 🏠 Home-Assistant-Integration

Integrieren Sie Ihren Router mit der REST-API in Home Assistant:

• Schlafenszeit-Automatisierungen: Blockieren Sie Tablets und Spielkonsolen der Kinder automatisch um 22:00 Uhr an Schultagen.

• Anwesenheitserkennung: Lösen Sie Automatisierungen aus, wenn bestimmte Telefone das Netzwerk betreten oder verlassen.

• Dashboard-Schalter: Erstellen Sie dedizierte „Internet blockieren / freigeben"-Schaltflächen auf Ihrem Home-Assistant-Lovelace-Dashboard.

✨ Funktionen

• 🏷️ Dauerhafte Geräte-Spitznamen – Gespeichert in SQLite (data/router.db), sodass Sie Geräte über menschenfreundliche Namen wie „Gästezimmer-TV" referenzieren können.

• 🎯 Intelligente Multi-Ziel-Auflösung – Blockieren/Freigeben/Abfragen über Spitzname, Hostname, IP-Adresse oder MAC-Adresse (unterstützt partielle/groß-/kleinschreibungsunabhängige Übereinstimmung).

• 🔍 Verbundene Geräte auflisten – Hostname, IP-Adresse, MAC-Adresse, aktiver Online-Status und Verbindungsschnittstelle (Ethernet, 2,4-GHz-802.11, 5-GHz-802.11ac).

• 🚫 Geräte blockieren – Internetzugriff rund um die Uhr für jedes Gerät über Kindersicherungsregeln blockieren.

• ✅ Geräte freigeben – Blockierungsregeln sofort entfernen.

• 📋 Blockierte Richtlinien auflisten – Alle aktiven Zugriffsbeschränkungsrichtlinien und Zeitpläne anzeigen.

• 🔄 Auto-Sync & selbstheilende Sitzungen – Automatische Neuanmeldung und Sitzungswiederherstellung, wenn Router-Sitzungen ablaufen.

• 🔐 Null Browser-Overhead – Reine kryptografische Authentifizierung über pycryptodome und requests.

🏗️ Architektur: Vier Interaktionsmöglichkeiten

📦 Installation

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

# Install dependencies
pip install -r requirements.txt

Abhängigkeiten: requests, pycryptodome, python-dotenv, fastapi, uvicorn, mcp

⚙️ Konfiguration

Erstellen Sie eine .env-Datei im Stammverzeichnis (oder kopieren Sie sie aus .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

🔒 Sicherheitshinweis: Die Dateien .env und data/*.db sind in .gitignore enthalten, sodass Ihre Router-Anmeldedaten und die lokale Datenbank niemals committet werden.

🌐 1. Web-Dashboard & REST-API

Starten Sie den Server:

python -m api.server

• Öffnen Sie http://localhost:8000/ in Ihrem Browser, um das Web-Dashboard anzuzeigen.

• Öffnen Sie http://localhost:8000/docs für die interaktive Swagger-API-Dokumentation.

REST-Endpunkte

🤖 2. MCP-Server-Nutzung (für KI-Agenten)

Stellen Sie Router-Tools KI-Agenten direkt über das Model Context Protocol (MCP) bereit.

Verfügbare MCP-Tools

• list_devices() – Gibt eine formatierte Tabelle mit Nickname, Hostname, IP, MAC, Active, Blocked und Interface zurück.

• set_device_nickname(target, nickname, notes=None) – Setzt oder aktualisiert den freundlichen Spitznamen eines Geräts.

• block_device(target, policy_name=None) – Blockiert Gerät per Spitzname (z. B. "Gästezimmer-TV"), Hostname, IP oder MAC.

• unblock_device(target) – Gibt Gerät per Spitzname, Hostname, IP oder MAC frei.

• list_blocked_devices() – Gibt aktive blockierte Geräte mit ihren Spitznamen und Richtlinien zurück.

MCP-Konfiguration

Fügen Sie diesen Server zu Ihrer MCP-Client-Konfiguration hinzu (z. B. claude_desktop_config.json oder mcp_config.json):

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

🖥️ 3. CLI-Nutzung

# 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. Python-Bibliotheksnutzung

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()

📁 Projektstruktur

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

⚠️ Hinweise & Haftungsausschluss

• Sitzungsablauf & Selbstheilung: Router-Sitzungen laufen nach Inaktivität natürlich ab. Die API- und MCP-Server verwalten die erneute Authentifizierung bei nachfolgenden Aufrufen automatisch.

• Kompatibilität der Kindersicherung: Unterstützt sowohl NEUE Firmware (NPCProfileList-gruppenbasierte Zugriffskontrolle) als auch ALTE Firmware (pc_config-Zugriffsrichtlinien).

• Getestete Hardware: Getestet auf Nokia G-2425G-A GPON Home Gateway (Airtel Xstream Fiber).

📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert – siehe die Datei LICENSE für Details.