home_router
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:
🌐 Web-Dashboard – Elegante Web-App im dunklen Glassmorphism-Stil mit Live-Suche, Spitznamen-Bearbeitung und 1-Klick-Blockieren/Freigeben-Schaltern.
🤖 MCP-Server – Ermöglicht KI-Agenten (wie Antigravity, Claude, Cursor) die Steuerung Ihres Wi-Fi und das Blockieren/Freigeben über freundliche Spitznamen.
⚡ REST-API (FastAPI) – Perfekt für Home Assistant, Webhooks und benutzerdefinierte Automatisierung.
🖥️ CLI – Sofortige Terminalbefehle und Bash-Skripting.
Related MCP server: tplink-mcp
🎯 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
pycryptodomeundrequests.
🏗️ Architektur: Vier Interaktionsmöglichkeiten
Schnittstelle | Am besten geeignet für | Einstiegspunkt |
Web-Dashboard | Visuelle Verwaltung, Spitznamen bearbeiten, Live-Geräteliste |
|
MCP-Server | KI-Agenten (Claude, Antigravity, Cursor) |
|
REST-API | Home Assistant, Node-RED, benutzerdefinierte Automatisierung |
|
CLI | Schneller Terminalzugriff, Cron-Jobs, Shell-Skripte |
|
📦 Installation
# Clone the repository
git clone https://github.com/surajnai567/airtel-router-api.git
cd airtel-router-api
# Install dependencies
pip install -r requirements.txtAbhä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
.envunddata/*.dbsind in.gitignoreenthalten, 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/docsfür die interaktive Swagger-API-Dokumentation.
REST-Endpunkte
Methode | Pfad | Beschreibung | Payload |
|
| Alle verbundenen Geräte mit Spitznamen & blockiertem Status auflisten | — |
|
| Alle blockierten Geräte mit Spitznamen auflisten | — |
|
| Freundlichen Spitznamen setzen oder löschen |
|
|
| Gerät per Spitzname, Hostname, IP oder MAC blockieren |
|
|
| Gerät per Spitzname, Hostname, IP oder MAC freigeben |
|
|
| Health-Check & Router-Verbindungsstatus | — |
🤖 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 mitNickname,Hostname,IP,MAC,Active,BlockedundInterfacezurü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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
IP intelligence, network diagnostics, and AI service availability tools for AI agents.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Control dedicated 4G mobile and residential proxies on mobileproxy.space from AI agents.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI assistants to interact with Ubiquiti UniFi network infrastructure for monitoring devices, managing clients, and performing configuration tasks like blocking/unblocking devices and viewing network health.101GPL 3.0
- AlicenseBqualityDmaintenanceEnables AI agents to manage TP-Link routers by listing clients, checking status, controlling Wi-Fi, and rebooting via natural language.332MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to interact with Xiaomi/Redmi routers, providing read-only queries and management capabilities such as device listing, port forwarding, DHCP reservations, and reboot control.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to manage Nokia G-240W-F fiber router settings, including router status, connected devices, optical power, Wi-Fi channel selection, Ethernet speeds, port forwards, DMZ, and gaming optimization through 12 tools.1MIT