net-ip-watch

English README

net-ip-watch 是一个零依赖、CLI 优先的 Node.js IP 变化监控工具。它默认监控公网出口 IP，也支持切换到本地网卡模式，适合盯指定网络接口的地址变化。

适用场景：

• 切换 Wi-Fi、热点、VPN 或代理后，确认公网出口 IP 是否发生变化
• 只盯某张本地网卡，忽略不相关的虚拟网卡或隧道网卡
• 在终端持续运行，地址变化时立即收到提示

检测到变化时，工具会：

• 在终端输出变化详情
• 触发终端响铃
• 在 macOS 上尝试发送系统通知

安装

要求 Node.js 18 及以上。

全局安装：

npm install -g net-ip-watch

不安装直接执行：

npx net-ip-watch --once

CLI 用法

默认持续监控公网出口 IP：

net-ip-watch

只查看当前公网 IP：

net-ip-watch --once

自定义轮询间隔，单位秒：

net-ip-watch --interval 2

切换到本地网卡模式：

net-ip-watch --target local

只监控指定网卡。可以重复传入 --interface，也可以使用逗号分隔：

net-ip-watch --target local --interface en0
net-ip-watch --target local --interface en0,utun0

查看帮助：

net-ip-watch --help

说明

• 默认目标是公网出口 IP，也就是外部服务看到的地址
• 公网 IP 查询内置多个 provider，某个服务失败时会自动回退
• --target local 会过滤回环地址和 IPv6 的 fe80:: 链路本地地址
• 如果机器上有 VPN、虚拟网卡或隧道网卡，建议结合 --interface 缩小监控范围
• 在非 macOS 平台上不会报错，只是不会发送系统通知

MCP Server

net-ip-watch 也可以作为 MCP server 运行，供 agent 或工具系统直接调用。

如果已经安装了包：

net-ip-watch-mcp

如果希望通过 npx 启动：

npx -y -p net-ip-watch net-ip-watch-mcp

示例 MCP 配置：

{
  "mcpServers": {
    "net-ip-watch": {
      "command": "npx",
      "args": ["-y", "-p", "net-ip-watch", "net-ip-watch-mcp"]
    }
  }
}

暴露的工具：

• get_public_ip：查询当前公网出口 IP，可选 timeoutMs
• get_local_ips：查询当前本地 IP，可选 interfaces

结构化返回示例：

{
  "ok": true,
  "target": "public",
  "entries": [
    {
      "name": "public",
      "family": "IPv4",
      "address": "154.84.135.10",
      "cidr": null,
      "source": "ipify"
    }
  ],
  "code": null,
  "message": null
}

当工具返回错误时，结果仍然是结构化的，只是 ok 会变成 false，同时带上稳定的 code，例如 INVALID_ARGUMENT、PUBLIC_IP_LOOKUP_FAILED、FETCH_UNAVAILABLE 或 INTERNAL_ERROR。

作为库使用

如果你要在脚本中复用，也可以直接使用导出的监控函数：

const {
  alertIpChange,
  collectLocalIPs,
  collectPublicIPs,
  startMonitoring
} = require("net-ip-watch");

示例：只获取一次当前公网 IP。

const { collectPublicIPs } = require("net-ip-watch");

async function main() {
  const entries = await collectPublicIPs();
  console.log(entries);
}

main().catch(console.error);