mcp-netgear-genie

A production-grade Model Context Protocol (MCP) server that connects AI assistants (Claude, Cursor, Antigravity, VS Code, Goose) directly to Netgear Genie cable modems (specifically the CM1000 DOCSIS 3.1 and compatible CM-series modems).

It transforms the modem's embedded ASP, JavaScript, and XML administrative web interface into strongly-typed tools, executive dashboards, and real-time RF signal diagnostics.

Supported Hardware

Tested and verified against physical hardware:

• Netgear CM1000 (DOCSIS 3.1, Hardware 2.02, Firmware V7.01.01+)

• Netgear CM1100 / CM1150V / CM1200

• Netgear CM2000 / CM2050V

• Netgear CM500 / CM600 / CM700 (DOCSIS 3.0 mode)

• Netgear CAX30 / CAX80 (Cable modem gateway status pages)

Related MCP server: iStoreOS MCP Server

Key Features

• 🌐 Single-Call Executive Dashboard (get_dashboard_summary):

  • Combines modem hardware identity, connection state, RF signal span, OFDM telemetry, and event log breakdown into a single call.

• 📡 Full DOCSIS 3.1 OFDM Channel Telemetry:

  • Extracts active subcarrier ranges (e.g. 296 ~ 7895), modulation profiles (0, 1, 2, 3), starting frequency (447.0 MHz), power levels, and SNR/MER.

• ⚙️ Startup Procedure Verification:

  • Parses the 6-step initialization procedure (Acquire Downstream Channel, Connectivity State, Boot State, Configuration File, Security, IP Provisioning Mode).

• 🩺 Automated RF Signal Health Diagnostics:

  • Evaluates downstream and upstream RF power against CableLabs industry specifications.

  • Flags hot/overdriven downstream power (> +10 dBmV), weak signals (< -10 dBmV), low SNR (< 33 dB), and excessive upstream transmit power (> 48 dBmV).

  • Provides actionable cabling and splitter remediation recommendations.

• 📜 Structured Event Log Decomposition:

  • Extracts clean error messages stripped of internal semicolon-separated parameters.

  • Parses CM MAC, CMTS MAC, and DOCSIS version into structured fields.

  • Produces an aggregate summary count of events by severity level (Critical, Error, Warning, Notice).

• 📊 Dual Visual Markdown & Programmatic JSON Output:

  • All tools accept format: "table" | "json" | "both".

  • Default "table" format renders rich GitHub-flavored Markdown tables mirroring the Netgear Web UI layout for AI conversations.

• 🔒 Zero-Config Authentication & Session Management:

  • Handles dynamic webToken extraction from GenieLogin.asp, HTTP 302 redirects, and SessionID cookie caching.

  • Automatically bypasses system proxy intercepts for 192.168.100.1 and .lan domains.

• 🛠️ Administrative Safety Guards:

  • Modem reboot and log-clearing tools require explicit confirm=True confirmation.

Installation

From Source / Git

pip install git+https://github.com/FrankXLT/mcp-netgear-genie.git

Local Development

git clone https://github.com/FrankXLT/mcp-netgear-genie.git
cd mcp-netgear-genie
pip install -e .

Quickstart & Client Configuration

1. Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "netgear-genie": {
      "command": "python3",
      "args": ["-m", "mcp_netgear_genie.server"],
      "env": {
        "NETGEAR_HOST": "http://192.168.100.1",
        "NETGEAR_USERNAME": "admin",
        "NETGEAR_PASSWORD": "your_modem_password"
      }
    }
  }
}

2. Cursor

Add to your project's .cursor/mcp.json or user settings:

{
  "mcpServers": {
    "netgear-genie": {
      "command": "python3",
      "args": ["-m", "mcp_netgear_genie.server"],
      "env": {
        "NETGEAR_HOST": "http://192.168.100.1",
        "NETGEAR_USERNAME": "admin",
        "NETGEAR_PASSWORD": "your_modem_password"
      }
    }
  }
}

3. Antigravity IDE

Add to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "netgear-genie": {
      "command": "python3",
      "args": ["-m", "mcp_netgear_genie.server"],
      "env": {
        "NETGEAR_HOST": "http://192.168.100.1",
        "NETGEAR_USERNAME": "admin",
        "NETGEAR_PASSWORD": "your_modem_password"
      }
    }
  }
}

Remote Docker & SSE Gateway Deployment

You can host mcp-netgear-genie centrally on a NAS (Synology, Unraid, TrueNAS) or server using Supergateway for network-wide access via Streamable HTTP / Server-Sent Events (SSE).

docker-compose.yml

version: '3.9'

services:
  mcp-netgear-genie:
    image: ghcr.io/supercorp-ai/supergateway:latest
    container_name: mcp-netgear-genie
    restart: unless-stopped
    entrypoint:
      - "sh"
      - "-c"
      - |
        which python3 >/dev/null 2>&1 || apk add --no-cache python3 py3-pip git
        pip list | grep -q mcp-netgear-genie || pip install --break-system-packages "git+https://github.com/FrankXLT/mcp-netgear-genie.git"
        exec node /usr/local/bin/supergateway --port 8000 --cors --outputTransport streamableHttp --streamableHttpPath /sse --stateful --stdio 'python3 -m mcp_netgear_genie.server'
    environment:
      - NETGEAR_HOST=http://192.168.100.1
      - NETGEAR_USERNAME=admin
      - NETGEAR_PASSWORD=your_modem_password
    ports:
      - "8000:8000"

Once running, AI clients can connect over SSE:

http://<your-server-ip>:8000/sse

Standalone CLI Usage

mcp-netgear-genie includes a full CLI for quick checks and scripting:

# Display modem hardware info
mcp-netgear-genie info

# Display active DOCSIS bonded channels & startup state
mcp-netgear-genie status

# Display automated RF health evaluation and recommendations
mcp-netgear-genie health

# View recent event logs filtered by priority
mcp-netgear-genie logs --priority Warning --limit 10

# Output raw JSON for scripts or piping to jq
mcp-netgear-genie status --json | jq '.downstream_channels[0]'

MCP Tools Reference

Resources Exposed

• netgear://modem/info: Static hardware and firmware identity.

• netgear://modem/cable-status: Live DOCSIS connection and channel status.

• netgear://modem/event-logs: Recent DOCSIS event logs.

Configuration Reference

DOCSIS RF Signal Reference Guide

The diagnostic engine evaluates your physical RF line using CableLabs and DOCSIS 3.0 / 3.1 standards:

Network Topology & DNS Setup (modem.lan)

Cable modems respond on 192.168.100.1 across their internal management interface. To map a clean local hostname like http://modem.lan:

Firewalla

1. Open the Firewalla App.

2. Navigate to Network -> DNS Service -> Custom DNS Rules.

3. Tap Add Rule:

   • Domain: modem.lan

   • IP Address: 192.168.100.1

4. Save and configure NETGEAR_HOST=http://modem.lan.

Pi-hole / pfSense / OPNsense / dnsmasq

Add an A record or static DNS host override:

address=/modem.lan/192.168.100.1

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details on code style, testing, and PR submissions.