iptime-mcp

英语 | 한국어

iptime-mcp

一个带安全门控的模型上下文协议（MCP）服务，无需反复打开 Web 管理面板即可管理 ipTIME 路由器。

它可以检查路由器状态，发现特定型号和固件支持的目录操作，并在网络、Wi-Fi、NAT、防火墙、VPN、DDNS、USB/NAS、系统和自动化功能中执行已确认的更改。

这是一个非官方社区项目，与 EFM Networks 或 ipTIME 无关。路由器 API 取决于固件，并未作为稳定的公共契约发布。

亮点

• 13 个专用 MCP 工具，而非数百个顶级工具
• 334 项已编入目录的路由器操作：171 项读取操作和 163 项写入操作
• 在 iUX3 上通过路由器的 api/has 方法进行运行时能力检查
• 支持检测 iUX3、Mobile iUX 和 classic CGI 接口
• 只读操作可直接执行
• 每项路由器更改都会使用短时有效、可审核的计划，且无需确认令牌
• 配置备份、恢复计划和固件升级计划
• 单路由器和多路由器配置
• 凭据和会话值脱敏
• 默认禁止使用公共纯 HTTP

目录涵盖管理、固件、备份与恢复、WAN/LAN/DHCP/DNS、路由与交换、无线网络和 EasyMesh、NAT 和端口转发、防火墙、QoS、VPN、DDNS、USB/NAS 服务、例程、历史记录、日志、主机扫描和 Wake-on-LAN。

兼容性

接口	支持情况
iUX3	使用 /cgi/service.cgi JSON RPC，并通过 api/has 检查每个已知方法
Mobile iUX	仅公开明确映射的读取操作
Classic CGI	仅公开明确映射的读取操作

固定操作目录基于在搭载固件 15.36.6 的 iUX3 应用中观察到的方法。目录中列出某个方法并不意味着每台路由器都支持它。选择操作前，务必使用 iptime_capabilities 检查目标路由器。

固件 16.00.0 引入了 ipTIME ID、EasyMesh 客户端连接固定和分页系统日志（官方发行说明）。这些新增功能尚未通过此目录验证。本服务直接连接到配置的路由器；不会通过 ipTIME ID 进行身份验证，也不提供云中继。不要根据固件版本或成功的状态查询推断新功能受到支持。对于日志，在将结果视为完整之前，请检查实际响应和特定固件的分页情况。仅公开经过验证的方法，未知的写入功能仍会被阻止。

对于固件 16.00.4，我们检查了官方 A2004SE UI 包：ACS CA 证书使用现有的 cwmp/set 方法，acs.cacert 中包含 PEM 文本（最多 8192 字节；"" 会移除证书）。UI 会发送完整的 active/acs/cpe 配置。因此，更改证书时必须提供所有这些字段，包括实际的 ACS/CPE 凭据；不接受部分配置和 [redacted] 占位符。cwmp.get 会隐藏密码，因此不能原样复制后再提交。如果无法安全提供完整的预期配置，请停止操作，不要应用更改。该计划仍属于严重风险，并会通过 cwmp/get 回读。使用私有 CA 的 HTTPS ACS 服务器需要相应的证书；不要禁用验证。这是对接口契约的验证，并非对所有型号的实时路由器兼容性认证。ipTIME ID/passkey 登录和新的 EasyMesh 控制仍不受支持，除非经过单独验证。

共享配置方法不接受通过 iptime_read 传入的配置参数；这些参数可能执行写入。请改用更改计划中的相应写入操作。观察到的 ddns.config 选择器 "iptime" 仍允许用于读取。

旧版支持有意限制为已知安全的映射，包括系统信息、DHCP 租约和配置、端口转发以及 Wake-on-LAN。旧版响应可能以原始文本形式返回。未知的旧版写入操作会被拒绝。

安全模型

更改路由器设置可能会中断互联网连接，或导致无法访问管理界面。因此，iptime-mcp 将读取与写入分开处理：

1. iptime_plan_change 或针对特定文件的规划工具会创建不可变更计划，不会更改路由器。
2. 计划会报告操作、参数、可用时的当前状态、风险和到期时间。
3. iptime_apply_change 仅使用计划的 plan_id 应用该计划；用户无需复制 APPLY <UUID> 令牌。

明确请求执行同一项更改，即表示已获得授权。只有当严重风险计划（例如固件、恢复、重置、凭据或存储格式操作）尚未得到明确授权时，客户端才应使用普通语言再次确认。MCP 客户端仍可显示其常规的破坏性工具审批提示。

计划在 10 分钟后过期，只能使用一次，包含完整性摘要，并按路由器串行处理。如果写入响应丢失，服务端会尝试回读，且不会自动重试写入。计划保存在内存中，并会在 MCP 进程重启时消失。

要求

• Node.js 22 或更高版本
• 可访问路由器管理端点的网络连接
• ipTIME 管理员用户名和密码
• 支持 stdio 服务的 MCP 客户端

请尽可能使用局域网地址、VPN 地址或可信的 HTTPS 端点。

从 npm 安装

在 MCP 客户端中将 npx -y iptime-mcp 用作 stdio 命令，并在其私有环境配置中设置 IPTIME_ROUTER_URL、IPTIME_ROUTER_USERNAME 和 IPTIME_ROUTER_PASSWORD。请将路由器 URL 保留在可信的局域网或 VPN 内。以下示例展示了等效的源码安装设置，适用于需要本地脚本路径的客户端。

从源码安装

git clone https://github.com/mikusnuz/iptime-mcp.git
cd iptime-mcp
npm ci
npm run build

可执行入口为 dist/server.js。

对于支持环境文件或可配置工作目录的客户端，请先创建本地 .env：

cp .env.example .env

填写路由器 URL、用户名和密码。.env 会被 Git 忽略，必须保留在本地。

MCP 客户端设置

请尽可能使用用户级配置，因为不应将路由器凭据提交到项目中。替换每个示例中的 /absolute/path/to/iptime-mcp。在 Windows 上，JSON 中可以使用正斜杠路径，例如 C:/Users/name/iptime-mcp/dist/server.js。如果桌面客户端找不到 node，请使用 macOS/Linux 上由 which node 或 Windows 上由 where node 显示的绝对路径。

客户端	用户级配置
Codex / ChatGPT 桌面版	设置 → MCP 服务 或 ~/.codex/config.toml
Claude Desktop	设置 → 开发者 → 编辑配置
Claude Code	claude mcp add --scope user
Cursor	~/.cursor/mcp.json
VS Code Agent 聊天	MCP：打开用户配置
GitHub Copilot CLI	~/.copilot/mcp-config.json
Gemini CLI	~/.gemini/settings.json

Codex / ChatGPT 桌面版

在 设置 → MCP 服务 中添加一个 stdio 服务，或将以下内容添加到 ~/.codex/config.toml。替换路径和凭据，保存并重启 MCP 服务。

[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、其 IDE 扩展和 ChatGPT 桌面应用在同一台 Codex 主机上共享 MCP 配置。当前客户端选项请参阅官方 MCP 配置指南。

如果你更倾向于使用本地 .env 文件，请保留 cwd 并省略 [mcp_servers.iptime.env] 表。

Claude Desktop

打开 设置 → 开发者 → 编辑配置，将以下 iptime 条目合并到 claude_desktop_config.json 中，保存并完全重启 Claude Desktop。请保留文件中的其他现有服务。

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

重启后，在聊天输入框中检查 连接器。请参阅官方 Claude Desktop 本地 MCP 指南。

Claude Code

使用 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

最后的 --transport 选项有意放在环境变量值之后，以免可变参数 --env 解析器将服务名称也包含进去。用户范围的配置存储在 ~/.claude.json 中。请参阅官方 Claude Code MCP 指南。

Cursor

创建或合并 ~/.cursor/mcp.json。此示例会读取上文创建的、被忽略的本地 .env：

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

重启 Cursor，然后检查 设置 → 工具与 MCP。也支持项目范围的 .cursor/mcp.json，但请勿将路由器凭据放入可能会被提交的文件中。请参阅官方 Cursor MCP 指南。

VS Code Agent 聊天 / GitHub Copilot Chat

从命令面板运行 MCP: Open User Configuration，并合并此配置。VS Code 使用顶层键 servers，而不是 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"
    }
  }
}

使用 MCP: List Servers 启动或检查服务，并在首次使用时接受服务信任提示。.vscode/mcp.json 可用于工作区范围的设置，但用户配置对路由器凭据更安全。请参阅VS Code 官方 MCP 设置指南和配置参考。

GitHub Copilot CLI

GitHub Copilot CLI 不会读取 VS Code 的 .vscode/mcp.json。请改为创建或合并 ~/.copilot/mcp-config.json：

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

配置的 cwd 可让 iptime-mcp 加载本地 .env。使用 copilot mcp list 验证连接。也支持项目级 .mcp.json 和 .github/mcp.json，但切勿提交路由器凭据。请参阅官方 Copilot CLI MCP 指南。

Gemini CLI

创建或合并 ~/.gemini/settings.json：

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

配置的 cwd 可让服务加载 .env。保持 trust 为 false，让 Gemini 在调用工具前继续询问，然后运行 gemini mcp list。如果当前文件夹不受信任，请运行 gemini trust。CLI 命令默认使用项目范围；手动注册时请使用 --scope user。请参阅官方 Gemini CLI MCP 指南。

其他 stdio MCP 客户端

将 node 用作命令，将 /absolute/path/to/iptime-mcp/dist/server.js 用作唯一参数，并传入 .env 中的 IPTIME_* 变量。不要假定所有客户端使用相同的 JSON 包装格式：例如，VS Code 使用 servers，而 Claude Desktop、Cursor、Copilot CLI 和 Gemini CLI 使用 mcpServers。

环境变量

单个路由器

变量	必需	默认值	说明
IPTIME_ROUTER_URL	是	—	使用 http 或 https 的路由器基础 URL
IPTIME_ROUTER_ID	否	default	作为 router_id 暴露的配置名称
IPTIME_ROUTER_USERNAME	登录时必需	—	路由器管理员用户名
IPTIME_ROUTER_PASSWORD	登录时必需	—	路由器管理员密码
IPTIME_ALLOW_INSECURE_REMOTE_HTTP	否	false	当主机名解析为公共地址时允许使用纯 HTTP
IPTIME_TLS_FINGERPRINT	否	—	SHA-256 证书指纹，可带或不带冒号；除常规 TLS 验证外还会检查此指纹
IPTIME_TIMEOUT_MS	否	12000	请求超时时间，限制在 1,000–60,000 ms

不得将凭据嵌入 IPTIME_ROUTER_URL。

服务还会从其工作目录加载 .env 文件。仅在本地使用时，才将 .env.example 复制为 .env；.env 和相关密钥文件已被 Git 忽略。

多个路由器

将 IPTIME_ROUTERS 设置为 JSON 数组。使用 username_env 和 password_env，让 JSON 包含环境变量名称而非凭据：

IPTIME_ROUTERS='[{"id":"home","url":"http://192.168.0.1","username_env":"HOME_ROUTER_USERNAME","password_env":"HOME_ROUTER_PASSWORD"},{"id":"office","url":"https://router.office.example","username_env":"OFFICE_ROUTER_USERNAME","password_env":"OFFICE_ROUTER_PASSWORD","timeout_ms":20000}]'
HOME_ROUTER_USERNAME=admin
HOME_ROUTER_PASSWORD=your-home-password
OFFICE_ROUTER_USERNAME=admin
OFFICE_ROUTER_PASSWORD=your-office-password

配置单个路由器时，可省略 router_id。配置多个路由器时，请向路由器工具传入目标 router_id。

MCP 工具

工具	用途
iptime_status	检测接口，在存在凭据时进行身份验证，并读取产品／系统状态
iptime_login	使用 MCP 环境中的凭据登录；可选提交 CAPTCHA 答案
iptime_logout	结束当前路由器管理员会话
iptime_capabilities	根据目标型号和固件检查目录中的操作
iptime_list_operations	按领域或模式列出本地、可审计的操作目录
iptime_read	执行一项只读目录操作
iptime_backup_config	保存新的 .config 备份文件，不覆盖现有文件
iptime_plan_change	创建通用路由器变更计划，但不应用变更
iptime_plan_firmware_upgrade	计算本地 .bin 镜像的哈希值，并创建严重风险升级计划
iptime_plan_config_restore	计算本地 .config 备份的哈希值，并创建严重风险恢复计划
iptime_apply_change	按 ID 应用一项待处理计划；无需确认令牌
iptime_cancel_change	取消一项待处理计划
iptime_list_plans	列出内存中待处理和已完成的计划

MCP 资源

URI	内容
iptime://configuration	已配置的路由器配置文件，不含凭据
iptime://operations	完整操作目录、领域、模式、风险和参数提示

推荐工作流

1. 调用 iptime_status 检测路由器并建立会话。
2. 调用 iptime_capabilities，也可按 wireless、network、vpn 或 usb 等领域筛选。
3. 使用 iptime_list_operations 查找确切的操作和参数提示。
4. 使用 iptime_read 执行读取操作。
5. 如需变更，创建计划并向用户展示其风险、参数、先前状态和过期时间。
6. 如果计划符合用户的具体请求，则直接应用，无需让用户重复提供令牌或计划 ID。对于尚未得到明确授权的严重风险变更，只需用自然语言询问一次。
7. 如果结果报告为未知，请先检查返回的验证状态，再进行任何其他操作。

一些实用的读取操作包括：

• product.info 和 system.info
• network.info 和 network.interface.lan.stations
• dhcpd.lease.show 和 dhcpd.reservedaddr.show
• wireless.client.show 和 wireless.channel.list
• portforward.get 和 upnp.relay
• firewall.get
• wg.client.show、wg.peer.show 和 vpncli.status.list
• ddns.config 和 ddns.status.get
• usb.show、usb.mount.list 和 nas.user.show
• syslog.show 和 wol.show

某些方法需要标量、数组或对象，而不是空对象。目录中的 paramsHint 和 defaultParams 字段说明了已知的参数约定。例如，列出 Wi-Fi 信道需要指定 "2g" 或 "5g" 等频段；DDNS 状态查询则需要已配置的主机名。

备份、恢复和固件

iptime_backup_config：

• 要求目标路径以 .config 结尾
• 必要时创建父目录
• 拒绝覆盖现有文件
• 使用仅所有者可访问的权限写入（0600）
• 拒绝空备份和大于 32 MiB 的文件

配置备份可能包含私有网络设置和机密信息。*.config 已加入 Git 忽略规则，绝不能提交。

固件和恢复计划会记录文件大小与 SHA-256 哈希值，并在上传前再次验证文件。固件镜像必须以 .bin 结尾；配置备份必须以 .config 结尾。系统不会验证固件镜像是否兼容路由器型号，因此请获取与确切型号对应的镜像，并仔细审查严重风险计划。

网络安全

• 除非设置 IPTIME_ALLOW_INSECURE_REMOTE_HTTP=true，否则不允许通过公共地址使用纯 HTTP。
• 启用此覆盖选项可能会暴露管理员密码和会话 Cookie。仅在无法使用 HTTPS 时，通过可信的专用隧道使用。
• 禁止重定向和跨源端点构造。
• 响应大小上限为 8 MiB，请求超时时间也有上限。
• 仅保留 ipTIME 会话 Cookie。
• MCP 输出中的密码、令牌、会话值、私钥、PSK 和类似字段都会被递归脱敏。
• 可选的 TLS 指纹会在正常证书验证后添加证书固定；它不会让不受信任的自签名证书变为有效。

请将 MCP 客户端配置文件视为机密，因为其中可能包含路由器密码。

CAPTCHA 和会话行为

如果路由器要求输入 CAPTCHA，iptime_login 会返回包含可用验证信息的 CAPTCHA_REQUIRED 错误。如有需要，请打开路由器管理页面，然后使用 captcha_code 重试 iptime_login。

会话过期时，读取操作会自动续期一次。发生身份验证错误或网络状态不明确时，写入操作绝不会自动重试。

开发

npm ci
npm run lint
npm test
npm run build

开发模式：

npm run dev

测试套件使用环回模拟路由器，无需实体设备。请勿在生产路由器上运行写入测试。

面向 AI Agent 的文件

• llms.txt 提供简明、机器可读的项目和工具摘要。
• AGENTS.md 包含代码 Agent 的仓库贡献规则和安全规则。
• templates/AGENTS.md 可复制到需要使用此 MCP 服务的项目中。
• templates/CLAUDE.md 为 Claude Code 项目提供等效的使用指南。

这些文件描述了实际的工具工作流和安全限制；其中不包含凭据或本地路由器详情。

许可证

MIT © 2026 mikusnuz