network-mcp

Read-only CLI access to managed network devices, over SSH or Telnet, exposed as an MCP connector. Give it an IP address; it logs in with the house credentials, works out whether it is a Cisco or an ADTRAN, pulls the config, strips the secrets out, and hands it back.

Built on the house MCP pattern (fastmcp resource-server + Entra OAuth, behind NPM on Portainer) — see ~/.claude/context/mcp-server-playbook.md.

"pull the config from 10.20.30.1"   ->  net_running_config
"is 10.20.30.1 up, and what is it?" ->  net_probe_device
"unsaved changes on 10.20.30.1?"    ->  net_config_diff
"back up these six routers"         ->  net_backup_configs

Status

Working end to end against real hardware, 2026-08-17. Pulled the running config from an ADTRAN Total Access 924e (AOS R10.9.5.E) at 192.0.2.90 via the relay: platform auto-detected, 454 lines, 47 secrets redacted, 4.8 seconds, no credential leakage. The relayuser relay account exists.

Not deployed — no Entra app, no Portainer stack, no NPM host, no GitHub repo. See PORTAINER_DEPLOY.md.

How it reaches devices

Neither this workstation nor the docker host can route to customer management networks. A relay can — so the server does exactly what an engineer does:

ssh relayuser@203.0.113.24     ->  telnet 192.0.2.90  ->  show running-config

Nothing is configured on the relay. No sshd_config edit, no reload, no TCP forwarding, no per-device rules. Create a user, and a new device IP works immediately. Mechanically this is netmiko's terminal-server pattern: connect with the terminal_server driver, drive the hop by hand, then redispatch() the live session onto the Cisco or ADTRAN driver (network_mcp/relay_shell.py). Vendor re-detection is another redispatch on the same session — no second login.

A tunnelled mode (NETMCP_JUMP_MODE=forward, network_mcp/jump.py) is also implemented and is technically cleaner, but it needs port forwarding enabled on a public-facing box. Shell mode is the default for that reason.

net_relay_status checks the relay on its own — login, telnet client present, and whether the relay can actually open a path to a given device. That's what separates "the relay is down" from "that router is down", which are otherwise identical from a device error.

This raises the stakes on NETMCP_ALLOWED_CIDRS. The relay is a shell; it reaches whatever it can reach. The MCP server's allowlist is the only thing bounding which addresses get logged into.

What it can reach

Cisco IOS / IOS-XE, NX-OS, IOS-XR, ASA; ADTRAN AOS (NetVanta, Total Access); Arista EOS; Juniper Junos; HP/Aruba ProCurve. The platform is detected from show version, so callers never have to say what a box is.

Tools

Tool	What it does
net_capabilities	What this connector is for — the front door
net_probe_device	Reachable? over what? which login? what platform? No config returned
net_running_config	The running config, redacted. section= filter for big ones
net_startup_config	The saved config
net_show	Any single show-style command
net_facts	Model, serial, software version, uptime
net_interfaces	Interface / IP / status summary
net_backup_configs	Many devices at once; status + hash per device, text on request
net_config_diff	Running vs startup (unsaved changes), or device A vs device B

Five prompts ship as the discovery surface in claude.ai (+ → Connectors → Add from network-mcp): Pull Device Config, Site Config Backup, Unsaved Changes Check, Device Triage, Compare Two Devices.

The three things that make this safe

This server is different from the others we run: it holds a shared admin credential for customer network equipment, and it is driven by a language model that reads untrusted text (tickets, emails, device banners, interface descriptions). "Now check 203.0.113.9" or "run configure terminal" can appear in any of those. So none of this is left to prompting.

1. It is read-only by construction, not by policy — device.py calls five netmiko methods and none of them write. There is no send_config_set, no config mode, no save/copy/erase/reload anywhere in the package. tests/test_readonly_surface.py parses the AST and fails if one appears. A change tool, if ever wanted, belongs in a separate server with its own Entra app and access group — the way tactical-rmm-mcp and tactical-rmm-audit-mcp are split.

2. guard.py decides what it may log in to — it resolves the target first, requires every address a name resolves to be permitted, and connects to the address it checked (no DNS-rebinding gap).

The allowlist is currently OPEN (NETMCP_ALLOWED_CIDRS=0.0.0.0/0,::/0) — John's call, 2026-08-17, because managed devices sit on private and public addresses across many customers and a hand-maintained list would be wrong more often than right during build-out. Loopback, link-local (incl. the 169.254.169.254 metadata address), multicast and reserved space are still refused.

Know what that trades away: the credentials are shared across the estate and Telnet sends them in cleartext, so an address arriving from a ticket, an email, an interface description or a device banner is acted on exactly like one an engineer typed. net_capabilities says so out loud and the server logs a warning at startup, so the posture is visible rather than buried in a value. Narrowing later: our own public blocks + RFC1918, or — better — allow only addresses documented as configurations in IT Glue, which is tighter than any CIDR list and makes documentation load-bearing.

3. Configs come back redacted — redact.py replaces enable secrets, local user hashes, SNMP communities, RADIUS/TACACS keys, IPSec PSKs, WiFi passphrases, BGP/OSPF authentication and inline private keys, keeping the left-hand side so config review and drift comparison still work. There is no tool parameter that turns this off; only the NETMCP_REDACT_SECRETS environment variable, changed deliberately by a person. An MCP result lands in a transcript permanently.

Plus: command allowlist (show, display, dir, ping, traceroute only — no chaining, no | tee/redirect/append), credentials selectable only by profile name and never returned, every Telnet session flagged in its own result as cleartext, and a per-call audit line carrying the Entra identity of the human who asked.

Local development

python -m venv .venv && .venv/Scripts/pip install -r requirements.txt pytest

cp .env.example .env

Fill in NETMCP_ALLOWED_CIDRS and one credential profile, then run the tests:

<your-workspace>/network-mcp/.venv/Scripts/python.exe -m pytest tests -q

Run it over stdio in Claude Code (MCP_TRANSPORT=stdio, the default):

<your-workspace>/network-mcp/.venv/Scripts/python.exe <your-workspace>/network-mcp/run_server.py

MCP_AUTH_ENABLED=false is for local stdio and MCP Inspector only. Never expose it — this server holds device credentials.

Layout

network_mcp/
  server.py        MCP tools and prompts
  device.py        netmiko sessions — the only module that touches a device
  guard.py         where it may log in, and what it may type
  redact.py        what is removed before output leaves the process
  credentials.py   profiles, held server-side, never returned
  vendors.py       per-platform commands, drivers, detection signatures
  archive.py       optional on-disk config archive
  config.py        environment -> settings
tests/             the security spec: guard, redaction, read-only surface
scripts/           setup_entra_app.ps1
docs/              ENTRA_SETUP_CHECKLIST.md

Known limits

• show archive and show boot are refused as a side effect of the filter rules. show bootvar works. Nobody has needed the other two yet.
• Vendor detection needs a reachable show version. A device with a login banner that swallows the first command, or an unusual platform, falls back to generic IOS-style commands and says so in warnings.
• Telnet is slow and fragile on old hardware. Raise NETMCP_GLOBAL_DELAY_FACTOR to 2 or 4 if output comes back truncated.
• The on-disk archive is unredacted by default (a redacted config cannot be restored, so it is not a backup). The volume is a credential store — back it up and treat it as one.
• Structured parsing is deliberately shallow. net_facts regexes a few fields and always returns the raw output alongside; anything richer is better done by the model reading the text than by a regex here that rots silently.