Iptime MCP

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.

Firmware 16.00.0 introduced ipTIME ID, EasyMesh client connection pinning, and paginated system logs (official release notes). These additions have not been validated against this catalog. This server connects directly to the configured router; it does not authenticate through ipTIME ID or provide its cloud relay. Do not infer support for new features from a firmware version or from a successful status query. For logs, inspect the actual response and firmware-specific pagination before treating a result as complete. Only verified methods are exposed, and unknown write capabilities remain blocked.

For firmware 16.00.4, the official A2004SE UI bundle was inspected: the ACS CA certificate uses the existing cwmp/set method with acs.cacert containing PEM text (up to 8192 bytes; "" removes the certificate). The UI sends the complete active/acs/cpe configuration. Certificate changes therefore require all these fields, including the actual ACS/CPE credentials; partial configurations and [redacted] placeholders are rejected. cwmp.get hides passwords and cannot be copied back as-is. If you cannot safely supply the complete intended configuration, stop without applying the change. The plan remains critical-risk and reads back through cwmp/get. HTTPS ACS servers with a private CA require the corresponding certificate; do not disable verification. This is interface-contract verification, not a live-router compatibility certification for every model. ipTIME ID/passkey login and new EasyMesh controls remain unsupported until separately verified.

Shared configuration methods accept no configuration parameters through iptime_read; those parameters can perform writes. Use the corresponding write operation through a change plan instead. The observed ddns.config selector "iptime" remains allowed for reads.

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. iptime_plan_change 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. iptime_apply_change 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 IPTIME_ROUTER_URL, IPTIME_ROUTER_USERNAME, and IPTIME_ROUTER_PASSWORD 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

git clone https://github.com/mikusnuz/iptime-mcp.git

cd iptime-mcp npm ci npm run build

The executable entry point is dist/server.js.

For clients that support an environment file or configurable working directory, create a local .env first:

cp .env.example .env

Fill in the router URL, username, and password. .env is ignored by Git and must remain local.

MCP client setup

Use a user-level configuration whenever possible because router credentials should not be committed to a project. Replace /absolute/path/to/iptime-mcp in every example. On Windows, forward-slash paths such as C:/Users/name/iptime-mcp/dist/server.js work in JSON. If a desktop client cannot find node, use the absolute path reported by which node on macOS/Linux or where node on Windows.

Codex / ChatGPT desktop

Add a stdio server in Settings → MCP servers, or add the following to ~/.codex/config.toml. Replace the path and credentials, save, and restart the MCP server.

[mcp_servers.iptime]

command = "node" args = ["/absolute/path/to/iptime-mcp/dist/server.js"] cwd = "/absolute/path/to/iptime-mcp" default_tools_approval_mode = "writes"

[mcp_servers.iptime.env] IPTIME_ROUTER_ID = "home" IPTIME_ROUTER_URL = "http://192.168.0.1" IPTIME_ROUTER_USERNAME = "admin" IPTIME_ROUTER_PASSWORD = "your-router-password"

Codex, its IDE extension, and the ChatGPT desktop app share the MCP configuration on the same Codex host. See the official MCP configuration guide for current client options.

If you prefer the local .env file, keep cwd and omit the [mcp_servers.iptime.env] table.

Claude Desktop

Open Settings → Developer → Edit Config, merge the following iptime entry into claude_desktop_config.json, save, and fully restart Claude Desktop. Keep any other existing servers in the file.

{

"mcpServers": { "iptime": { "command": "node", "args": ["/absolute/path/to/iptime-mcp/dist/server.js"], "env": { "IPTIME_ROUTER_ID": "home", "IPTIME_ROUTER_URL": "http://192.168.0.1", "IPTIME_ROUTER_USERNAME": "admin", "IPTIME_ROUTER_PASSWORD": "your-router-password" } } } }

Check Connectors in the chat composer after restart. See the official Claude Desktop local MCP guide.

Claude Code

Register the server for all projects with the Claude Code CLI:

claude mcp add \

--scope user \ --env IPTIME_ROUTER_ID=home \ --env IPTIME_ROUTER_URL=http://192.168.0.1 \ --env IPTIME_ROUTER_USERNAME=admin \ --env IPTIME_ROUTER_PASSWORD=your-router-password \ --transport stdio iptime \ -- node /absolute/path/to/iptime-mcp/dist/server.js

claude mcp get iptime

The final --transport option intentionally comes after the environment values so the variadic --env parser does not consume the server name. The user-scoped configuration is stored in ~/.claude.json. See the official Claude Code MCP guide.

Cursor

Create or merge ~/.cursor/mcp.json. This example reads the ignored local .env created above:

{

"mcpServers": { "iptime": { "type": "stdio", "command": "node", "args": ["/absolute/path/to/iptime-mcp/dist/server.js"], "cwd": "/absolute/path/to/iptime-mcp", "envFile": "/absolute/path/to/iptime-mcp/.env" } } }

Restart Cursor, then check Settings → Tools & MCP. Project-scoped .cursor/mcp.json is also supported, but do not put router credentials in a file that may be committed. See the official Cursor MCP guide.

VS Code agent chat / GitHub Copilot Chat

Run MCP: Open User Configuration from the Command Palette and merge this configuration. VS Code uses the top-level key servers, not mcpServers.

{

"servers": { "iptime": { "type": "stdio", "command": "node", "args": ["/absolute/path/to/iptime-mcp/dist/server.js"], "cwd": "/absolute/path/to/iptime-mcp", "envFile": "/absolute/path/to/iptime-mcp/.env" } } }

Start or inspect it with MCP: List Servers and accept the server trust prompt on first use. .vscode/mcp.json is available for workspace-scoped setup, but the user configuration is safer for router credentials. See the official VS Code MCP setup and configuration reference.

GitHub Copilot CLI

GitHub Copilot CLI does not read VS Code's .vscode/mcp.json. Create or merge ~/.copilot/mcp-config.json instead:

{

"mcpServers": { "iptime": { "type": "stdio", "command": "node", "args": ["/absolute/path/to/iptime-mcp/dist/server.js"], "cwd": "/absolute/path/to/iptime-mcp", "tools": ["*"] } } }

The configured cwd lets iptime-mcp load the local .env. Verify the connection with copilot mcp list. Project-level .mcp.json and .github/mcp.json are also supported, but never commit router credentials. See the official Copilot CLI MCP guide.

Gemini CLI

Create or merge ~/.gemini/settings.json:

{

"mcpServers": { "iptime": { "command": "node", "args": ["/absolute/path/to/iptime-mcp/dist/server.js"], "cwd": "/absolute/path/to/iptime-mcp", "trust": false } } }

The configured cwd lets the se