iptime-mcp

**English** | [한국어](README.ko.md)

# 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

| Interface | Support |
|---|---|
| iUX3 | Uses `/cgi/service.cgi` JSON RPC and checks each known method with `api/has` |
| Mobile iUX | Exposes only explicitly mapped read operations |
| Classic CGI | Exposes only explicitly mapped read operations |

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. `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 <UUID>` 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

```sh
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:

```sh
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.

| Client | User-level configuration |
|---|---|
| Codex / ChatGPT desktop | **Settings → MCP servers** or `~/.codex/config.toml` |
| Claude Desktop | **Settings → Developer → Edit Config** |
| Claude Code | `claude mcp add --scope user` |
| Cursor | `~/.cursor/mcp.json` |
| VS Code agent chat | **MCP: Open User Configuration** |
| GitHub Copilot CLI | `~/.copilot/mcp-config.json` |
| Gemini CLI | `~/.gemini/settings.json` |

### 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.

```toml
[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](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) 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.

```json
{
  "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](https://modelcontextprotocol.io/quickstart/user).

### Claude Code

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

```sh
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](https://code.claude.com/docs/en/mcp).

### Cursor

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

```json
{
  "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](https://cursor.com/docs/mcp).

### 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`.

```json
{
  "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](https://code.visualstudio.com/docs/agent-customization/mcp-servers) and [configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

### GitHub Copilot CLI

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

```json
{
  "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](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers).

### Gemini CLI

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

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