Iptime MCP server

English | 한국어

iptime-mcp

A safety-gated Model Context Protocol (MCP) server for operating ipTIME routers without repeatedly opening the web admin panel.

It can inspect router state, discover which catalogued operations a specific model and firmware support, and perform confirmed changes across networking, Wi-Fi, NAT, firewall, VPN, DDNS, USB/NAS, system, and automation features.

This is an unofficial community project and is not affiliated with EFM Networks or ipTIME. Router APIs are firmware-dependent and are not published as a stable public contract.

Highlights

• 13 focused MCP tools instead of hundreds of top-level tools
• 334 catalogued router operations: 171 reads and 163 writes
• Runtime capability checks on iUX3 through the router's api/has method
• Detection for iUX3, Mobile iUX, and classic CGI interfaces
• Read-only operations can run directly
• Every router change uses a short-lived, reviewable plan without confirmation tokens
• Configuration backup, restore planning, and firmware upgrade planning
• Single-router and multi-router profiles
• Credential and session-value redaction
• Public plain HTTP blocked by default

The catalog covers administration, firmware, backup and restore, WAN/LAN/DHCP/DNS, routing and switching, wireless and EasyMesh, NAT and port forwarding, firewall, QoS, VPN, DDNS, USB/NAS services, routines, history, logs, host scanning, and Wake-on-LAN.

Compatibility

The fixed operation catalog is based on methods observed in an iUX3 application shipped with firmware 15.36.6. A method appearing in the catalog does not mean every router supports it. Always use iptime_capabilities for the target router before choosing an operation.

Legacy support is intentionally limited to known-safe mappings for system information, DHCP leases and configuration, port forwarding, and Wake-on-LAN. Legacy responses may be returned as raw text. Unknown legacy writes are rejected.

Safety model

Router changes can interrupt internet access or make the admin interface unreachable. iptime-mcp therefore separates reading from writing:

1. iptimeplanchange or a file-specific planning tool creates an immutable plan without changing the router.
2. The plan reports the operation, parameters, current state when available, risk, and expiry.
3. iptimeapplychange applies that exact plan using only its plan_id; users never need to copy an APPLY token.

A specific request for the same change is sufficient authorization. Clients should ask once more in ordinary language only when a critical-risk plan, such as firmware, restore, reset, credential, or storage-format work, was not already explicitly authorized. MCP clients may still show their normal destructive-tool approval prompt.

Plans expire after 10 minutes, are single-use, include an integrity digest, and are serialized per router. When a write response is lost, the server attempts a readback and does not retry the write automatically. Plans are held in memory and disappear when the MCP process restarts.

Requirements

• Node.js 22 or later
• Network access to the router admin endpoint
• An ipTIME administrator username and password
• An MCP client with stdio server support

Use a LAN address, a VPN address, or a trusted HTTPS endpoint whenever possible.

Install from npm

Use npx -y iptime-mcp as the stdio command in an MCP client and set IPTIMEROUTERURL, IPTIMEROUTERUSERNAME, and IPTIMEROUTERPASSWORD in its private environment configuration. Keep the router URL on a trusted LAN or VPN. The examples below show the equivalent source-install setup for clients that need a local script path.

Install from source

Shortened. The full README is on GitHub.