Nokia / Airtel GPON Home Router API & Web Dashboard

Nokia G-2425G-A GPON Home Gateway（Airtel Xstream Fiber などのISPで一般的に採用）を、Webダッシュボード、MCP（Model Context Protocol）、REST API、CLI で制御・自動化・管理できます。永続的な**デバイスニックネーム（SQLite）**に対応し、ブラウザ自動化は一切不要です！

💡 このプロジェクトが生まれた理由

問題点

ほとんどのホームファイバールーター（AirtelのNokia GPON ONTなど）には、スマートホームエコシステム向けの公式APIや連携機能がありません。次のようなことをしたい場合、

• 現在Wi-Fiに接続されているデバイスを確認する、

• わかりやすいニックネームを割り当てる（例："Akanksha Phone"、"Guestroom TV"）、

• 特定のデバイスのインターネットアクセスをブロックする（例：子どものスクリーンタイム管理）、

• または時間帯やスマートホームの状態に基づいてネットワークルールを自動化する...

...といった場合、手動でブラウザを開き、動作の遅いWebポータルを操作し、認証情報を入力し、複数の階層化された設定メニューをクリックして進むしかありません。

さらに悪いことに、ルーターのWebポータルは複雑なクライアントサイドハイブリッド暗号化方式（カスタムSJCL JavaScriptによるRSA-1024 + AES-128-CBC）を採用しているため、単純なcurlスクリプトや標準的なHTTPリクエストは失敗します。多くの開発者は、SeleniumやPuppeteerのような重くて壊れやすいブラウザ自動化に頼らざるを得ません。

解決策

このプロジェクトは、ルーターのRSA + AES暗号化ハンドシェイクを純粋なPythonで完全にリバースエンジニアリングしています。

ルーターの内部エンドポイントと直接通信し、サブ秒の応答時間を実現、ブラウザのオーバーヘッドはゼロです。永続的なデバイスメタデータ（ニックネーム、カスタムメモ、初回/最終検出日時）を保存するローカルSQLiteデータベースと組み合わせ、そのコアエンジンを4つのすぐに使えるインターフェースにまとめています：

1. 🌐 Webダッシュボード — ライブ検索、ニックネーム編集、1クリックのブロック/ブロック解除トグルを備えた、洗練されたダークグラスモーフィズムのWebアプリ。

2. 🤖 MCPサーバー — AIエージェント（Antigravity、Claude、Cursorなど）がWi-Fiを制御し、わかりやすいニックネームでブロック/ブロック解除できるようにします。

3. ⚡ REST API（FastAPI） — Home Assistant、Webhook、カスタム自動化に最適です。

4. 🖥️ CLI — 即座に使えるターミナルコマンドとbashスクリプト。

Related MCP server: OpenWRT SSH MCP Server

🎯 実際のユースケース

1. 🤖 AIエージェントによる音声・チャット制御（MCP経由）

このプロジェクトをMCP互換のAIアシスタント（例：Claude Desktop、Antigravity IDE、Cursor）に接続します。次のように話しかけるだけで済みます：

「デバイス f6:cf:28:1c:bd:e5 にニックネーム 'Akanksha Phone' を設定して。」
「Guestroom TV のインターネットアクセスをブロックして。」
「Living Room TV は今Wi-Fiに接続されている？」
「Akanksha Phone のブロックを解除して。」

AIエージェントが接続デバイスを調べ、ニックネーム/ホスト名/IP/MACで対象を特定し、ルーター上で自動的にアクションを実行します。

2. 🌐 ビジュアルWebダッシュボード

http://localhost:8000/ を開くと、レスポンシブなWeb UIですべての接続デバイスを監視できます：

• ライブ統計バー： 総デバイス数、オンライン中のデバイス数、ブロック数、カスタムニックネーム数。

• インスタント検索＆フィルター： すべて、オンライン、ブロック済み、カスタムニックネームでフィルタリング。

• インラインニックネームエディター： 任意のデバイスにわかりやすいニックネームと場所のメモを割り当て。

• 1クリックのブロック/ブロック解除： 処理中に即座に表示されるローディングスピナーとトースト通知でアクセスを切り替え。

3. 🏠 Home Assistant連携

REST APIを使用してルーターをHome Assistantに統合します：

• 就寝時オートメーション： 学校がある日の午後10時に、子どものタブレットやゲーム機を自動的にブロック。

• 在室検知： 特定のスマートフォンがネットワークに参加または離脱したときにオートメーションをトリガー。

• ダッシュボードトグル： Home AssistantのLovelaceダッシュボードに専用の「インターネットをブロック/ブロック解除」スイッチボタンを作成。

✨ 特徴

• 🏷️ 永続的なデバイスニックネーム — SQLite（data/router.db）に保存されるため、"Guestroom TV" のような人間にわかりやすい名前でデバイスを参照できます。

• 🎯 スマートなマルチターゲット解決 — ニックネーム、ホスト名、IPアドレス、またはMACアドレスでブロック/ブロック解除/照会が可能（部分一致・大文字小文字を区別しないマッチングに対応）。

• 🔍 接続デバイスの一覧表示 — ホスト名、IPアドレス、MACアドレス、オンライン状態、接続インターフェース（Ethernet、2.4GHz 802.11、5GHz 802.11ac）。

• 🚫 デバイスのブロック — ペアレンタルコントロールルールにより、任意のデバイスのインターネットアクセスを24時間365日ブロック。

• ✅ デバイスのブロック解除 — ブロックルールを即座に削除。

• 📋 ブロック済みポリシーの一覧表示 — アクティブなアクセス制限ポリシーとスケジュールをすべて表示。

• 🔄 自動同期＆自己修復セッション — ルーターのセッションが期限切れになった場合に自動再ログインとセッション復旧を実行。

• 🔐 ブラウザオーバーヘッドゼロ — pycryptodome と requests による純粋な暗号認証。

🏗️ アーキテクチャ：4つの操作方法

📦 インストール

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

# Install dependencies
pip install -r requirements.txt

依存関係： requests、pycryptodome、python-dotenv、fastapi、uvicorn、mcp

⚙️ 設定

ルートディレクトリに .env ファイルを作成します（または .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

🔒 セキュリティに関する注意： .env ファイルと data/*.db ファイルは .gitignore に含まれているため、ルーターの認証情報とローカルデータベースがコミットされることはありません。

🌐 1. Webダッシュボード＆REST API

サーバーを起動します：

python -m api.server

• ブラウザで http://localhost:8000/ を開くと、Webダッシュボードが表示されます。

• 対話型のSwagger APIドキュメントは http://localhost:8000/docs で確認できます。

RESTエンドポイント

🤖 2. MCPサーバーの使用方法（AIエージェント向け）

Model Context Protocol（MCP）を使用して、ルーターのツールをAIエージェントに直接公開します。

利用可能なMCPツール

• list_devices() — Nickname、Hostname、IP、MAC、Active、Blocked、Interface を含む整形されたテーブルを返します。

• set_device_nickname(target, nickname, notes=None) — デバイスのニックネームを設定または更新します。

• block_device(target, policy_name=None) — ニックネーム（例："Guestroom TV"）、ホスト名、IP、またはMACでデバイスをブロックします。

• unblock_device(target) — ニックネーム、ホスト名、IP、またはMACでデバイスのブロックを解除します。

• list_blocked_devices() — アクティブなブロック済みデバイスをニックネームとポリシー付きで返します。

MCP設定

このサーバーをMCPクライアント設定（例：claude_desktop_config.json または mcp_config.json）に追加します：

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

🖥️ 3. 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. 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()

📁 プロジェクト構造

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

⚠️ 注意事項と免責事項

• セッションの期限切れと自己修復： ルーターのセッションは、非アクティブ状態が続くと自然にタイムアウトします。APIサーバーとMCPサーバーは、その後の呼び出しで自動的に再認証を管理します。

• ペアレンタルコントロールの互換性： NEWファームウェア（NPCProfileList グループベースのアクセス制御）とOLDファームウェア（pc_config アクセスポリシー）の両方に対応。

• テスト済みハードウェア： Nokia G-2425G-A GPON Home Gateway（Airtel Xstream Fiber）でテスト済み。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細は LICENSE ファイルを参照してください。