Skip to main content
Glama

fios-mcp

An MCP server that lets an AI assistant manage a Verizon Fios CR1000A router — port forwards, DHCP reservations, static routes, DNS, DMZ, UPnP, device blocking and more — through the router's own local web interface. No cloud, no Verizon account, nothing leaves your LAN.

Not affiliated with or endorsed by Verizon. This drives the router's web UI the same way your browser does. A bad change can cut off your network; try it on an isolated bench router first, keep the policy file strict, and read every preview before confirming.

Why it is safe to point an AI at your router

  • Every change is two-phase. A write tool first returns a preview of exactly what will change plus a state_etag. Only a second call with confirm=true and that etag applies it. If anything changed in between — say you edited the same setting in the web UI — it refuses with conflict.

  • Every change is verified. After writing, the tool reads the router back and reports verified: true|false.

  • Your policy wins. policy.toml holds a DNS allowlist, entries that may never be deleted, and whether DMZ is allowed at all (it isn't, by default).

  • Secrets never leave. Wi-Fi keys, guest/IoT passwords and the admin password the router returns in clear text are redacted from every response.

  • Fail-closed on unknown firmware. Writes are refused on firmware versions this tool has not been verified against.

  • Dangerous operations don't exist. No tools for factory reset, firmware upgrade, the admin password or remote administration. Moving the LAN is off unless policy.toml allows it.

  • TLS is pinned, not disabled, and the router's admin sessions are used sparingly (one per process, logged out on exit).

Related MCP server: mtik-mcp

Tools

Area

Tools

Status

router_status, router_firmware, router_diagnostics, ping, read_router_page (redacted raw view of any page), get_policy

Devices

list_connected_devices, list_dhcp_leases, list_arp_table, list_blocked_devices, block_device, unblock_device

Wi-Fi

get_wifi_summary, set_wifi_radio, set_wifi_network (primary / guest / IoT: on/off, SSID, password, security)

Port forwarding

list_port_forwarding, add_port_forwarding, delete_port_forwarding, set_port_forwarding_enabled

DHCP

get_lan_settings, list_dhcp_reservations, add_dhcp_reservation, delete_dhcp_reservation

Routing & DNS

list_static_routes, add_static_route, delete_static_route, get_dns_settings, set_dns_settings

Security

get_firewall_settings, get_remote_admin_settings, get_dmz_settings, set_dmz, get_upnp_settings, set_upnp

System

reboot_router, set_lan_settings (router address, mask, DHCP pool)

Migration

snapshot_config, list_snapshots, diff_config, check_desired_state, apply_desired_state

Where a tool also exists in common TP-Link router MCP servers it has the same name, so moving settings from one router to the other is a side-by-side job.

Things the CR1000A does that you should know

  • DHCP reservations in .100–.150 are silently ignored. That block is reserved for Verizon-managed devices: the router stores such a reservation but never hands the address out. This tool refuses them up front.

  • At most 10 admin sessions at a time by default (session_max), expiring after 10 idle minutes. Clients that never log out lock you out of the web UI for a while; this one logs out.

  • Every CR1000A presents the same certificate (mynetworksettings.com, issued by "Verizon Fios CA", valid to 2068). Pinning it blocks other certificates but does not identify your particular router.

  • LAN clients use the router as their DNS server, so the WAN DNS setting is what every device ultimately resolves through.

  • IPv6 DNS is a separate setting, automatic by default. With IPv6 on the WAN, the router can forward lookups to the ISP's IPv6 resolvers even when IPv4 DNS is set manually. The DNS tools warn about this (ipv6_dns_auto); changing IPv6 DNS is not supported yet, so set it in the web UI or turn IPv6 off on the WAN if every lookup must go through your chosen resolver.

  • The LAN's .100–.150 is handed to Verizon set-top boxes (DHCP option 60) and moves with the subnet; the DHCP pool cannot sit entirely inside it.

  • Wi-Fi saves take about 80 seconds: the router holds the request open until Wi-Fi has restarted. With mesh (SON) on — the default — the 2.4 GHz and 5 GHz networks share one SSID and password.

  • Moving the LAN ends the session. set_lan_settings previews every reservation, forward, route or DMZ entry the new subnet would strand, then reports the new address to point FIOS_ROUTER_URL at.

  • 20 static-route slots, 127 DHCP reservation slots, 128 port forwards.

Install

Python 3.11+.

pip install "git+https://github.com/vehoelite/fios-mcp"

Set up

  1. Put the router's admin password in a file only you can read:

    mkdir -p -m 700 ~/.config/fios-mcp
    printf '%s' 'your-admin-password' > ~/.config/fios-mcp/password && chmod 600 ~/.config/fios-mcp/password
  2. Pin the router's certificate (shows it and asks first):

    fios-mcp trust            # or: fios-mcp trust --url https://192.168.1.1
  3. Write ~/.config/fios-mcp/policy.toml (chmod 600) — see examples/policy.example.toml. Without one, DNS changes and DMZ are refused.

  4. Check that it can log in:

    FIOS_ROUTER_PASSWORD_FILE=~/.config/fios-mcp/password fios-mcp check

Claude Code

claude mcp add fios -e FIOS_ROUTER_PASSWORD_FILE=$HOME/.config/fios-mcp/password -- fios-mcp serve

Other MCP clients

{
  "mcpServers": {
    "fios": {
      "command": "fios-mcp",
      "args": ["serve"],
      "env": { "FIOS_ROUTER_PASSWORD_FILE": "/home/you/.config/fios-mcp/password" }
    }
  }
}

Variable

Default

FIOS_ROUTER_URL

https://192.168.1.1

FIOS_ROUTER_PASSWORD_FILE / FIOS_ROUTER_PASSWORD

— (file preferred; must be chmod 600)

FIOS_ROUTER_PIN

~/.config/fios-mcp/router.pem

FIOS_MCP_POLICY

~/.config/fios-mcp/policy.toml

FIOS_MCP_ALLOW_UNVERIFIED_FIRMWARE

unset (writes refused on unverified firmware)

The same keys (url, password_file, pin_file, policy_file) can go in ~/.config/fios-mcp/config.toml.

Migrating to (or between) routers

Describe what the router should hold in a TOML file (examples/desired.toml), then ask the assistant to check_desired_state and apply_desired_state. It adds or fixes what is missing — each item through the same validation and read-back as the individual tools — and never removes anything extra. snapshot_config before and diff_config after show exactly what changed.

Tested firmware

Firmware

Build date

Verified

Notes

3.3.1.2

2024-12-19

2026-10-29

every tool, on a bench router, with read-back (LAN moved away and back)

Running another version? Reads work; writes are refused until the contract test passes on it — please open an issue with the result.

Development

pip install -e ".[dev]"
pytest                     # mock router, no hardware needed
ruff check fios_mcp tests
  • tests/mock_router.py imitates the router (rotating field ids, CSRF tokens, session cap, JavaScript responses) so the whole tool suite runs in CI.

  • tests/contract/bench_e2e.py runs every tool over stdio MCP against a real router — on an isolated bench only: FIOS_ROUTER_PASSWORD_FILE=… FIOS_MCP_CONTRACT_WRITES=1 python tests/contract/bench_e2e.py

  • tests/test_no_leaks.py fails on real-looking MACs and public IPs. Put your own MACs, WAN IP, SSIDs and domain in a gitignored .scrub-denylist (one per line) and it checks those too.

  • How the router's API works is documented in spec/DISCOVERY.md; the architecture in docs/DESIGN.md.

Credits

Written by Claude Opus 5.5 (Anthropic's AI model), with hardware setup, bench testing and direction by vehoelite. Everything in this repository — the protocol notes in spec/, the client, the safety layer and the tests — came out of that collaboration, with every write path checked on a real CR1000A before it shipped.

Thank you to Brishen, whose verizon_router_client (MIT) was the first public Python client for the CR1000A. It showed that this router's web API could be scripted at all, and that was the starting point for this project. Thanks also to skircr115/ha-verizonFiOS for its Home Assistant work on the same router. No code from either project is included here: the client was written from the router's own web UI code and verified on hardware.

License

MIT — see LICENSE.

Available Tools

41 tools
add_dhcp_reservationC
Idempotent

Reserve an IP for a MAC. Refuses .100-.150 (reserved for Verizon devices). Two-phase.

Inputs: ip (required), mac (required), name, confirm, +2 more. Returns: object

add_port_forwardingB
Idempotent

Forward external port(s) (e.g. ["443"] or ["1000-2000"]) to a LAN host. Two-phase.

internal_port: only if different from the external port. replace=true updates an existing rule on the same port instead of refusing.

Inputs: name (required), internal_ip (required), external_ports (required), confirm, +5 more. Returns: object

add_static_routeC
Idempotent

Route a network (CIDR, e.g. 10.99.0.0/24) via a LAN gateway. Two-phase.

Inputs: gateway (required), destination (required), metric, confirm, +1 more. Returns: object

apply_desired_stateA
Idempotent

Apply a desired-state TOML file item by item (never removes extra entries).

Without confirm, returns the plan. With confirm, applies each item through the same validation and read-back as the individual tools, stopping at the first failure.

Inputs: path (required), confirm. Returns: object

block_deviceC
Idempotent

Block a device (by MAC) from the network. Two-phase.

Inputs: mac (required), confirm, expected_etag. Returns: object

check_desired_stateA
Read-only

Compare the router to a desired-state TOML file; lists what is missing or different.

Inputs: path (required). Returns: object

delete_dhcp_reservationC
Destructive

Remove the reservation for a MAC. Two-phase.

Inputs: mac (required), confirm, expected_etag. Returns: object

delete_port_forwardingC
Destructive

Delete a port forward by name, or by external port (+ protocol). Two-phase.

Inputs: name, confirm, protocol, expected_etag, +1 more. Returns: object

delete_static_routeC
Destructive

Delete the static route to a network (CIDR). Two-phase.

Inputs: destination (required), confirm, expected_etag. Returns: object

diff_configC
Read-only

Differences between two snapshots, or a snapshot and the live router ("live").

Inputs: snapshot_a (required), snapshot_b. Returns: object

get_dmz_settingsC
Read-only

DMZ host settings.

Inputs: no named parameters. Returns: object

get_dns_settingsA
Read-only

WAN DNS (IPv4 mode/servers in use, and IPv6 DNS mode). LAN clients use the router.

Warns when IPv6 DNS is automatic: that is a second path to the ISP's resolvers.

Inputs: no named parameters. Returns: object

get_firewall_settingsC
Read-only

Firewall security levels (IPv4/IPv6).

Inputs: no named parameters. Returns: object

get_lan_settingsC
Read-only

LAN address, mask, DHCP range and lease time.

Inputs: no named parameters. Returns: object

get_policyC
Read-only

The owner's policy.toml guard-rails as loaded.

Inputs: no named parameters. Returns: object

get_remote_admin_settingsC
Read-only

Whether remote (WAN-side) administration and WAN ping/traceroute replies are enabled.

Inputs: no named parameters. Returns: object

get_upnp_settingsC
Read-only

Whether UPnP (devices opening ports themselves) is enabled.

Inputs: no named parameters. Returns: object

get_wifi_summaryB
Read-only

Physical radios per band, mesh state, and the primary/guest/IoT networks (SSID, on/off, security). Never includes keys.

Inputs: no named parameters. Returns: object

list_arp_tableC
Read-only

The router's ARP table.

Inputs: no named parameters. Returns: object

list_blocked_devicesC
Read-only

Devices blocked from the network.

Inputs: no named parameters. Returns: object

list_connected_devicesB
Read-only

Devices the router knows, with MAC, IP, hostname and whether they are active.

Inputs: active_only. Returns: object

list_dhcp_leasesA
Read-only

Current DHCP leases (hostname, IP, MAC, seconds left).

Inputs: no named parameters. Returns: object

list_dhcp_reservationsC
Read-only

DHCP reservations (MAC -> fixed IP).

Inputs: no named parameters. Returns: object

list_port_forwardingC
Read-only

Port forwarding rules with their ports, target and enabled state.

Inputs: no named parameters. Returns: object

list_snapshotsB
Read-only

Ids of saved snapshots, oldest first.

Inputs: no named parameters. Returns: object

list_static_routesB
Read-only

Configured IPv4 static routes (max 20); optionally the router's live routing table.

Inputs: include_live_table. Returns: object

pingA
Read-only

Ping an IPv4 address from the router itself (1-20 packets).

Inputs: target (required), count. Returns: object

read_router_pageA
Read-only

Raw (redacted) contents of one router page, for settings without a dedicated tool.

Pages: see the fios://pages resource.

Inputs: page (required). Returns: object

reboot_routerA
Destructive

Reboot the router (~4 minutes of downtime). Without confirm, only previews.

Inputs: confirm. Returns: object

router_diagnosticsB
Read-only

Connection, session and policy state of this MCP server (never secrets).

Inputs: no named parameters. Returns: object

router_firmwareB
Read-only

Firmware version/date and whether this tool has been verified against it.

Inputs: no named parameters. Returns: object

router_statusC
Read-only

Model, firmware, WAN address and DNS in use, LAN address.

Inputs: no named parameters. Returns: object

set_dmzB
Destructive

Enable (needs features.allow_dmz in policy.toml) or disable the DMZ host. Two-phase.

Inputs: enabled (required), ip, confirm, expected_etag. Returns: object

set_dns_settingsB
Idempotent

Set WAN DNS. Manual servers must be in policy.toml's allowlist. Two-phase.

Inputs: mode (required), confirm, servers, expected_etag. Returns: object

set_lan_settingsA
Destructive

Change the router's LAN address, mask and DHCP pool (needs features.allow_lan_change).

The preview lists reservations, forwards, routes and DMZ entries the new subnet would strand. If the address changes the router moves and this session ends: the result gives the new URL; the MCP server must be restarted with FIOS_ROUTER_URL pointing there. Two-phase.

Inputs: ip (required), mask, confirm, dhcp_end, +4 more. Returns: object

set_port_forwarding_enabledB
Idempotent

Enable or disable a port forward without deleting it. Two-phase.

Inputs: name (required), enabled (required), confirm, expected_etag. Returns: object

set_upnpC
Idempotent

Enable or disable UPnP. Two-phase.

Inputs: enabled (required), confirm, expected_etag. Returns: object

set_wifi_networkA
Idempotent

Change a Wi-Fi network: on/off, SSID, password (8-63 chars) and/or security. band is for the primary network only (default: all bands). The password is checked by read-back but never returned. Two-phase; confirming takes 1-2 minutes.

Inputs: network (required), band, ssid, confirm, +4 more. Returns: object

set_wifi_radioA
Idempotent

Turn a physical Wi-Fi radio on or off (e.g. when another access point serves Wi-Fi). Two-phase; the router restarts Wi-Fi, so confirming takes 1-2 minutes.

Inputs: band (required), enabled (required), confirm, expected_etag. Returns: object

snapshot_configA
Read-only

Save every readable setting to a local snapshot file (0600); returns its id.

Inputs: no named parameters. Returns: object

unblock_deviceC
Idempotent

Unblock a previously blocked device. Two-phase.

Inputs: mac (required), confirm, expected_etag. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 41 tools

    Disambiguation4/5

    Most tools map cleanly to a resource+action pair (get/set_dns_settings, add/delete/list_port_forwarding, block/unblock_device), and descriptions explicitly disambiguate close pairs like list_dhcp_leases vs list_dhcp_reservations. The only soft spots are the informational cluster (router_status, router_firmware, router_diagnostics, get_remote_admin_settings) and the catch-all read_router_page, which slightly overlap in intent.

    Naming Consistency4/5

    Overwhelmingly consistent snake_case verb_noun convention with a predictable get_/set_/list_/add_/delete_/block_ scheme, plus a well-signaled 'two-phase' confirm semantic shared across mutators. Minor deviations are the noun-first router_status / router_firmware / router_diagnostics and the bare ping, which break the get_-prefix family.

    Tool Count3/5

    41 tools is heavy, but the domain is genuinely broad (Wi-Fi, DHCP, routing, DNS, firewall/DMZ/UPnP, port forwarding, snapshots, desired-state). Several small single-purpose readers (get_firewall_settings, get_dmz_settings, get_upnp_settings, get_remote_admin_settings) could be consolidated into one security-settings tool, which is why this sits at borderline rather than well-scoped.

    Completeness4/5

    Nearly every write surface has full lifecycle support: DHCP reservations, static routes, port forwarding (including enable/disable without delete), device blocking, Wi-Fi networks, plus snapshot/diff/desired-state workflows that cover bulk and audit use cases. Gaps are limited: get_remote_admin_settings and get_firewall_settings have no setters, and the guard-railed policy likely makes those deliberately read-only.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to monitor and control Nokia G-2425G-A GPON home routers (e.g., Airtel) via natural language, including listing connected devices, and blocking or unblocking internet access for specific devices.
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to audit, inspect, and safely configure MikroTik RouterOS v7 routers through tools for connection testing, system status, security audits, firewall mangle management, routing, DHCP leases, sanitized exports, containers, and adlist queries.
      239 npm
      GPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables LLM/MCP clients to read and, when explicitly allowed, modify TP-Link Archer AX53 router settings directly over the LAN using the router's own web protocol, without a browser or cloud account. It is read-first, write-gated, and lockout-aware, with tools for clients, DHCP, Wi-Fi, access control, presence history, and other router operations.
      MIT