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

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" }
    }
  }
}

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

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.