Nokia / Airtel GPON Home Router API & Web Dashboard

通过 Web 仪表盘、MCP（Model Context Protocol）、REST API 和 CLI 控制、自动化并管理您的 Nokia G-2425G-A GPON Home Gateway（通常由 Airtel Xstream Fiber 和其他 ISP 部署）——支持持久化 设备昵称（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）。

解决方案

本项目使用纯 Python 完整逆向工程了路由器的 RSA + AES 加密握手。

它直接与路由器的内部端点通信，响应时间低于一秒，且零浏览器开销。它结合本地 SQLite 数据库 存储持久化设备元数据（昵称、自定义备注、首次/最后在线时间），并将该核心引擎封装为四个开箱即用的接口：

1. 🌐 Web 仪表盘 — 时尚的深色玻璃拟态 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 中监控所有已连接设备：

• 实时统计栏： 设备总数、当前在线、已阻止数量和自定义昵称数量。

• 即时搜索与筛选： 按全部、在线、已阻止或自定义昵称筛选。

• 内联昵称编辑器： 为任何设备分配友好昵称和位置备注。

• 一键阻止/取消阻止： 通过即时进行中的加载动画和 Toast 通知切换访问权限。

3. 🏠 Home Assistant 集成

使用 REST API 将您的路由器集成到 Home Assistant 中：

• 就寝自动化： 在上学日的晚上 10:00 自动阻止孩子的平板电脑和游戏主机。

• 存在检测： 当特定手机加入或离开网络时触发自动化。

• 仪表盘开关： 在您的 Home Assistant Lovelace 仪表盘上创建专用的“阻止/取消阻止互联网”开关按钮。

✨ 功能特性

• 🏷️ 持久化设备昵称 — 存储在 SQLite（data/router.db）中，因此您可以通过类似 "Guestroom TV" 的友好名称引用设备。

• 🎯 智能多目标解析 — 按 昵称、主机名、IP 地址 或 MAC 地址 阻止/取消阻止/查询（支持部分匹配和不区分大小写匹配）。

• 🔍 列出已连接设备 — 主机名、IP 地址、MAC 地址、当前在线状态和连接接口（以太网、2.4GHz 802.11、5GHz 802.11ac）。

• 🚫 阻止设备 — 通过家长控制规则 24/7 阻止任何设备访问互联网。

• ✅ 取消阻止设备 — 立即移除阻止规则。

• 📋 列出已阻止策略 — 查看所有有效的访问限制策略和时间计划。

• 🔄 自动同步与自愈会话 — 如果路由器会话过期，自动重新登录并恢复会话。

• 🔐 零浏览器开销 — 通过 pycryptodome 和 requests 进行纯加密认证。

🏗️ 架构：四种交互方式

📦 安装

# 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 仪表盘。

• 打开 http://localhost:8000/docs 获取交互式 Swagger API 文档。

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 服务器会在后续调用中自动管理重新认证。

• 家长控制兼容性： 同时支持 新 固件（NPCProfileList 基于组的访问控制）和 旧 固件（pc_config 访问策略）。

• 已测试硬件： 已在 Nokia G-2425G-A GPON Home Gateway（Airtel Xstream Fiber）上测试。

📄 许可证

本项目基于 MIT 许可证授权 - 有关详细信息，请参阅 LICENSE 文件。