fios-mcp
Manages a Verizon Fios CR1000A router through its local web interface, with tools for status and diagnostics, connected devices and device blocking, Wi-Fi radio/network settings, port forwarding, DHCP reservations and LAN settings, static routes, DNS, firewall, DMZ, UPnP, remote-admin readout, reboots, and config snapshot/migration workflows. All writes are two-phase previews with etags and read-back verification, gated by a policy file and pinned TLS.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@fios-mcp forward port 8080 to my server at 192.168.1.50"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 withconfirm=trueand that etag applies it. If anything changed in between — say you edited the same setting in the web UI — it refuses withconflict.Every change is verified. After writing, the tool reads the router back and reports
verified: true|false.Your policy wins.
policy.tomlholds 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.tomlallows 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 |
|
Devices |
|
Wi-Fi |
|
Port forwarding |
|
DHCP |
|
Routing & DNS |
|
Security |
|
System |
|
Migration |
|
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–.150are 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–.150is 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_settingspreviews every reservation, forward, route or DMZ entry the new subnet would strand, then reports the new address to pointFIOS_ROUTER_URLat.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
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/passwordPin the router's certificate (shows it and asks first):
fios-mcp trust # or: fios-mcp trust --url https://192.168.1.1Write
~/.config/fios-mcp/policy.toml(chmod 600) — seeexamples/policy.example.toml. Without one, DNS changes and DMZ are refused.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 serveOther MCP clients
{
"mcpServers": {
"fios": {
"command": "fios-mcp",
"args": ["serve"],
"env": { "FIOS_ROUTER_PASSWORD_FILE": "/home/you/.config/fios-mcp/password" }
}
}
}Variable | Default |
|
|
| — (file preferred; must be |
|
|
|
|
| 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 teststests/mock_router.pyimitates the router (rotating field ids, CSRF tokens, session cap, JavaScript responses) so the whole tool suite runs in CI.tests/contract/bench_e2e.pyruns 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.pytests/test_no_leaks.pyfails 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 indocs/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 toolsadd_dhcp_reservationCIdempotent
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_forwardingBIdempotent
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_routeCIdempotent
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_stateAIdempotent
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_deviceCIdempotent
Block a device (by MAC) from the network. Two-phase.
Inputs: mac (required), confirm, expected_etag. Returns: object
check_desired_stateARead-only
Compare the router to a desired-state TOML file; lists what is missing or different.
Inputs: path (required). Returns: object
delete_dhcp_reservationCDestructive
Remove the reservation for a MAC. Two-phase.
Inputs: mac (required), confirm, expected_etag. Returns: object
delete_port_forwardingCDestructive
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_routeCDestructive
Delete the static route to a network (CIDR). Two-phase.
Inputs: destination (required), confirm, expected_etag. Returns: object
diff_configCRead-only
Differences between two snapshots, or a snapshot and the live router ("live").
Inputs: snapshot_a (required), snapshot_b. Returns: object
get_dmz_settingsCRead-only
DMZ host settings.
Inputs: no named parameters. Returns: object
get_dns_settingsARead-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_settingsCRead-only
Firewall security levels (IPv4/IPv6).
Inputs: no named parameters. Returns: object
get_lan_settingsCRead-only
LAN address, mask, DHCP range and lease time.
Inputs: no named parameters. Returns: object
get_policyCRead-only
The owner's policy.toml guard-rails as loaded.
Inputs: no named parameters. Returns: object
get_remote_admin_settingsCRead-only
Whether remote (WAN-side) administration and WAN ping/traceroute replies are enabled.
Inputs: no named parameters. Returns: object
get_upnp_settingsCRead-only
Whether UPnP (devices opening ports themselves) is enabled.
Inputs: no named parameters. Returns: object
get_wifi_summaryBRead-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_tableCRead-only
The router's ARP table.
Inputs: no named parameters. Returns: object
list_blocked_devicesCRead-only
Devices blocked from the network.
Inputs: no named parameters. Returns: object
list_connected_devicesBRead-only
Devices the router knows, with MAC, IP, hostname and whether they are active.
Inputs: active_only. Returns: object
list_dhcp_leasesARead-only
Current DHCP leases (hostname, IP, MAC, seconds left).
Inputs: no named parameters. Returns: object
list_dhcp_reservationsCRead-only
DHCP reservations (MAC -> fixed IP).
Inputs: no named parameters. Returns: object
list_port_forwardingCRead-only
Port forwarding rules with their ports, target and enabled state.
Inputs: no named parameters. Returns: object
list_snapshotsBRead-only
Ids of saved snapshots, oldest first.
Inputs: no named parameters. Returns: object
list_static_routesBRead-only
Configured IPv4 static routes (max 20); optionally the router's live routing table.
Inputs: include_live_table. Returns: object
pingARead-only
Ping an IPv4 address from the router itself (1-20 packets).
Inputs: target (required), count. Returns: object
read_router_pageARead-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_routerADestructive
Reboot the router (~4 minutes of downtime). Without confirm, only previews.
Inputs: confirm. Returns: object
router_diagnosticsBRead-only
Connection, session and policy state of this MCP server (never secrets).
Inputs: no named parameters. Returns: object
router_firmwareBRead-only
Firmware version/date and whether this tool has been verified against it.
Inputs: no named parameters. Returns: object
router_statusCRead-only
Model, firmware, WAN address and DNS in use, LAN address.
Inputs: no named parameters. Returns: object
set_dmzBDestructive
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_settingsBIdempotent
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_settingsADestructive
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_enabledBIdempotent
Enable or disable a port forward without deleting it. Two-phase.
Inputs: name (required), enabled (required), confirm, expected_etag. Returns: object
set_upnpCIdempotent
Enable or disable UPnP. Two-phase.
Inputs: enabled (required), confirm, expected_etag. Returns: object
set_wifi_networkAIdempotent
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_radioAIdempotent
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_configARead-only
Save every readable setting to a local snapshot file (0600); returns its id.
Inputs: no named parameters. Returns: object
unblock_deviceCIdempotent
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
Scored across 41 tools
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.
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.
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.
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
Related MCP Connectors
Logs your AI agent into websites, catches verification codes, and asks you before anything risky.
Verified playbooks for websites: check before your agent browses, report how it went after.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables 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.3MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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 npmGPL 3.0
- 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 gradedqualityBmaintenanceEnables 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