iptime-mcp

Un servidor MCP con protección de seguridad para gestionar routers ipTIME en funciones de red, Wi-Fi, VPN, NAT y sistema.

GitHubPrueba este MCPPatrocinado

Documentación

English | 한국어

iptime-mcp

Un servidor de Protocolo de Contexto de Modelo (MCP) con protección de seguridad para operar routers ipTIME sin abrir repetidamente el panel de administración web.

Puede inspeccionar el estado del router, descubrir qué operaciones catalogadas admiten un modelo y firmware específicos, y realizar cambios confirmados en redes, Wi-Fi, NAT, firewall, VPN, DDNS, USB/NAS, sistema y funciones de automatización.

Este es un proyecto comunitario no oficial y no está afiliado a EFM Networks ni a ipTIME. Las API del router dependen del firmware y no se publican como un contrato público estable.

Características destacadas

13 herramientas MCP enfocadas en lugar de cientos de herramientas de nivel superior
334 operaciones de router catalogadas: 171 lecturas y 163 escrituras
Verificaciones de capacidad en tiempo de ejecución en iUX3 mediante el método api/has del router
Detección de interfaces iUX3, Mobile iUX y CGI clásicas
Las operaciones de solo lectura pueden ejecutarse directamente
Cada cambio en el router utiliza un plan breve y revisable sin tokens de confirmación
Copia de seguridad de configuración, planificación de restauración y planificación de actualización de firmware
Perfiles de un solo router y de múltiples routers
Redacción de credenciales y valores de sesión
HTTP plano público bloqueado por defecto

El catálogo cubre administración, firmware, copia de seguridad y restauración, WAN/LAN/DHCP/DNS, enrutamiento y conmutación, redes inalámbricas y EasyMesh, NAT y reenvío de puertos, firewall, QoS, VPN, DDNS, servicios USB/NAS, rutinas, historial, registros, escaneo de hosts y Wake-on-LAN.

Compatibilidad

Interfaz	Soporte
iUX3	Usa JSON RPC `/cgi/service.cgi` y verifica cada método conocido con `api/has`
Mobile iUX	Expone solo operaciones de lectura explícitamente mapeadas
CGI clásico	Expone solo operaciones de lectura explícitamente mapeadas

El catálogo fijo de operaciones se basa en métodos observados en una aplicación iUX3 incluida con el firmware 15.36.6. Que un método aparezca en el catálogo no significa que todos los routers lo admitan. Utilice siempre iptime_capabilities para el router de destino antes de elegir una operación.

El soporte heredado se limita intencionalmente a asignaciones conocidas y seguras para información del sistema, concesiones y configuración DHCP, reenvío de puertos y Wake-on-LAN. Las respuestas heredadas pueden devolverse como texto sin formato. Las escrituras heredadas desconocidas se rechazan.

Modelo de seguridad

Los cambios en el router pueden interrumpir el acceso a Internet o hacer que la interfaz de administración sea inalcanzable. iptime-mcp por lo tanto separa la lectura de la escritura:

iptime_plan_change o una herramienta de planificación específica de archivos crea un plan inmutable sin cambiar el router.
El plan informa la operación, los parámetros, el estado actual cuando está disponible, el riesgo y la caducidad.
iptime_apply_change aplica ese plan exacto usando solo su plan_id; los usuarios nunca necesitan copiar un token APPLY <UUID>.

Una solicitud específica para el mismo cambio es autorización suficiente. Los clientes deben preguntar una vez más en lenguaje ordinario solo cuando un plan de riesgo crítico, como trabajo de firmware, restauración, reinicio, credenciales o formato de almacenamiento, no fue ya autorizado explícitamente. Los clientes MCP pueden seguir mostrando su aviso normal de aprobación de herramientas destructivas.

Los planes caducan después de 10 minutos, son de un solo uso, incluyen un resumen de integridad y se serializan por router. Cuando se pierde una respuesta de escritura, el servidor intenta una lectura de verificación y no reintenta la escritura automáticamente. Los planes se mantienen en memoria y desaparecen cuando se reinicia el proceso MCP.

Requisitos

Node.js 22 o posterior
Acceso de red al endpoint de administración del router
Un nombre de usuario y contraseña de administrador de ipTIME
Un cliente MCP con soporte de servidor stdio

Use una dirección LAN, una dirección VPN o un endpoint HTTPS de confianza siempre que sea posible.

Instalar desde npm

Use npx -y iptime-mcp como comando stdio en un cliente MCP y establezca IPTIME_ROUTER_URL, IPTIME_ROUTER_USERNAME y IPTIME_ROUTER_PASSWORD en su configuración de entorno privada. Mantenga la URL del router en una LAN o VPN de confianza. Los ejemplos a continuación muestran la configuración equivalente de instalación desde el código fuente para clientes que necesitan una ruta de script local.

Instalar desde el código fuente

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

El punto de entrada ejecutable es dist/server.js.

Para clientes que admiten un archivo de entorno o un directorio de trabajo configurable, cree un .env local primero:

cp .env.example .env

Complete la URL del router, el nombre de usuario y la contraseña. .env es ignorado por Git y debe permanecer local.

Configuración del cliente MCP

Use una configuración a nivel de usuario siempre que sea posible porque las credenciales del router no deben comprometerse en un proyecto. Reemplace /absolute/path/to/iptime-mcp en cada ejemplo. En Windows, las rutas con barras diagonales como C:/Users/name/iptime-mcp/dist/server.js funcionan en JSON. Si un cliente de escritorio no puede encontrar node, use la ruta absoluta informada por which node en macOS/Linux o where node en Windows.

Cliente	Configuración a nivel de usuario
Codex / ChatGPT de escritorio	Configuración → Servidores MCP o `~/.codex/config.toml`
Claude Desktop	Configuración → Desarrollador → Editar configuración
Claude Code	`claude mcp add --scope user`
Cursor	`~/.cursor/mcp.json`
Chat de agente de VS Code	MCP: Abrir configuración de usuario
GitHub Copilot CLI	`~/.copilot/mcp-config.json`
Gemini CLI	`~/.gemini/settings.json`

Codex / ChatGPT de escritorio

Agregue un servidor stdio en Configuración → Servidores MCP, o agregue lo siguiente a ~/.codex/config.toml. Reemplace la ruta y las credenciales, guarde y reinicie el servidor 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, su extensión de IDE y la aplicación de escritorio de ChatGPT comparten la configuración de MCP en el mismo host de Codex. Consulte la guía oficial de configuración de MCP para conocer las opciones actuales del cliente.

Si prefiere el archivo .env local, mantenga cwd y omita la tabla [mcp_servers.iptime.env].

Claude Desktop

Abra Configuración → Desarrollador → Editar configuración, combine la siguiente entrada iptime en claude_desktop_config.json, guarde y reinicie completamente Claude Desktop. Mantenga cualquier otro servidor existente en el archivo.

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

Verifique Conectores en el compositor de chat después de reiniciar. Consulte la guía oficial de MCP local de Claude Desktop.

Claude Code

Registre el servidor para todos los proyectos con la CLI de Claude Code:

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

La opción final --transport se coloca intencionalmente después de los valores de entorno para que el analizador variádico --env no consuma el nombre del servidor. La configuración con ámbito de usuario se almacena en ~/.claude.json. Consulte la guía oficial de MCP de Claude Code.

Cursor

Cree o combine ~/.cursor/mcp.json. Este ejemplo lee el .env local ignorado creado anteriormente:

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

Reinicie Cursor y luego verifique Configuración → Herramientas y MCP. El .cursor/mcp.json con ámbito de proyecto también es compatible, pero no ponga credenciales del router en un archivo que pueda comprometerse. Consulte la guía oficial de MCP de Cursor.

Chat de agente de VS Code / GitHub Copilot Chat

Ejecute MCP: Abrir configuración de usuario desde la Paleta de comandos y combine esta configuración. VS Code usa la clave de nivel superior servers, no 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"
    }
  }
}

Inícielo o inspecciónelo con MCP: Listar servidores y acepte el aviso de confianza del servidor en el primer uso. .vscode/mcp.json está disponible para la configuración con ámbito de espacio de trabajo, pero la configuración de usuario es más segura para las credenciales del router. Consulte la configuración oficial de MCP de VS Code y la referencia de configuración.

GitHub Copilot CLI

GitHub Copilot CLI no lee el .vscode/mcp.json de VS Code. Cree o combine ~/.copilot/mcp-config.json en su lugar:

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

El cwd configurado permite que iptime-mcp cargue el .env local. Verifique la conexión con copilot mcp list. Los .mcp.json y .github/mcp.json a nivel de proyecto también son compatibles, pero nunca comprometa las credenciales del router. Consulte la guía oficial de MCP de Copilot CLI.

Gemini CLI

Cree o combine ~/.gemini/settings.json:

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

El cwd configurado permite que el servidor cargue .env. Mantenga trust en falso para que Gemini continúe preguntando antes de las llamadas a herramientas, luego ejecute gemini mcp list. Si la carpeta actual no es de confianza, ejecute gemini trust. El comando CLI usa por defecto el ámbito de proyecto; use --scope user al registrarlo manualmente. Consulte la guía oficial de MCP de Gemini CLI.

Otros clientes MCP stdio

Use node como comando, /absolute/path/to/iptime-mcp/dist/server.js como su único argumento y pase las variables IPTIME_* desde .env. No asuma que todos los clientes usan el mismo envoltorio JSON: por ejemplo, VS Code usa servers, mientras que Claude Desktop, Cursor, Copilot CLI y Gemini CLI usan mcpServers.

Variables de entorno

Un solo router

Variable	Requerida	Predeterminado	Descripción
`IPTIME_ROUTER_URL`	Sí	—	URL base del router usando `http` o `https`
`IPTIME_ROUTER_ID`	No	`default`	Nombre de perfil expuesto como `router_id`
`IPTIME_ROUTER_USERNAME`	Para inicio de sesión	—	Nombre de usuario administrador del router
`IPTIME_ROUTER_PASSWORD`	Para inicio de sesión	—	Contraseña de administrador del router
`IPTIME_ALLOW_INSECURE_REMOTE_HTTP`	No	`false`	Permite HTTP plano cuando el nombre de host se resuelve a una dirección pública
`IPTIME_TLS_FINGERPRINT`	No	—	Huella digital de certificado SHA-256, con o sin dos puntos, verificada además de la validación TLS normal
`IPTIME_TIMEOUT_MS`	No	`12000`	Tiempo de espera de solicitud, limitado a 1,000–60,000 ms

Las credenciales no deben incrustarse en IPTIME_ROUTER_URL.

El servidor también carga un archivo .env desde su directorio de trabajo. Copie .env.example a .env solo para uso local; .env y los archivos secretos relacionados son ignorados por Git.

Múltiples routers

Establezca IPTIME_ROUTERS en una matriz JSON. Use username_env y password_env para que el JSON contenga nombres de variables de entorno en lugar de credenciales:

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

Cuando se configura un router, router_id puede omitirse. Con múltiples routers, pase el router_id de destino a las herramientas del router.

Herramientas MCP

Herramienta	Propósito
`iptime_status`	Detectar la interfaz, autenticarse cuando existen credenciales y leer el estado del producto/sistema
`iptime_login`	Iniciar sesión con credenciales del entorno MCP; opcionalmente enviar una respuesta CAPTCHA
`iptime_logout`	Finalizar la sesión de administración actual del router
`iptime_capabilities`	Verificar operaciones catalogadas contra el modelo y firmware de destino
`iptime_list_operations`	Listar el catálogo de operaciones local y auditable por dominio o modo
`iptime_read`	Ejecutar una operación de catálogo de solo lectura
`iptime_backup_config`	Guardar un nuevo archivo de copia de seguridad `.config` sin sobrescribir un archivo existente
`iptime_plan_change`	Crear un plan genérico de cambio de router sin aplicarlo
`iptime_plan_firmware_upgrade`	Calcular el hash de una imagen `.bin` local y crear un plan de actualización de riesgo crítico
`iptime_plan_config_restore`	Calcular el hash de una copia de seguridad `.config` local y crear un plan de restauración de riesgo crítico
`iptime_apply_change`	Aplicar un plan pendiente por ID; no se requiere token de confirmación
`iptime_cancel_change`	Cancelar un plan pendiente
`iptime_list_plans`	Listar planes pendientes y completados en memoria

Recursos MCP

URI	Contenido
`iptime://configuration`	Perfiles de router configurados con credenciales omitidas
`iptime://operations`	Catálogo completo de operaciones, dominios, modos, riesgos y sugerencias de parámetros

Flujo de trabajo recomendado

Llame a iptime_status para detectar el router y establecer una sesión.
Llame a iptime_capabilities, opcionalmente filtrado por un dominio como wireless, network, vpn o usb.
Use iptime_list_operations para encontrar la operación exacta y la sugerencia de parámetros.
Ejecute lecturas con iptime_read.
Para un cambio, cree un plan y muestre su riesgo, parámetros, estado anterior y caducidad al usuario.
Si el plan coincide con la solicitud específica del usuario, aplíquelo sin pedirle que repita un token o ID de plan. Pregunte una vez en lenguaje natural solo para un cambio de riesgo crítico que no fue ya autorizado explícitamente.
Si el resultado se informa como desconocido, inspeccione el estado de verificación devuelto antes de hacer cualquier otra cosa.

Las operaciones de lectura útiles incluyen:

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

Algunos métodos requieren un escalar, un arreglo o un objeto en lugar de un objeto vacío. Los campos paramsHint y defaultParams del catálogo describen convenciones conocidas. Por ejemplo, el listado de canales Wi-Fi necesita una banda como "2g" o "5g", y el estado de DDNS necesita el nombre de host configurado.

Copia de seguridad, restauración y firmware

iptime_backup_config:

requiere un destino que termine en .config
crea directorios padre cuando es necesario
se niega a sobrescribir un archivo existente
escribe con permisos solo para el propietario (0600)
rechaza copias de seguridad vacías y archivos mayores de 32 MiB

Las copias de seguridad de configuración pueden contener ajustes de red privados y secretos. *.config es ignorado por Git y nunca debe ser confirmado.

Los planes de firmware y restauración registran el tamaño del archivo y el hash SHA-256, y luego verifican el archivo nuevamente inmediatamente antes de la carga. Las imágenes de firmware deben terminar en .bin; las copias de seguridad de configuración deben terminar en .config. Una imagen de firmware no se valida para la compatibilidad con el modelo del router, así que obtén la imagen correcta para el modelo exacto y revisa cuidadosamente el plan de riesgo crítico.

Seguridad de red

El HTTP plano de dirección pública se rechaza a menos que IPTIME_ALLOW_INSECURE_REMOTE_HTTP=true.
Habilitar esa anulación puede exponer la contraseña del administrador y la cookie de sesión. Úsala solo a través de un túnel privado de confianza cuando HTTPS sea imposible.
Las redirecciones y la construcción de endpoints entre orígenes están bloqueadas.
Las respuestas están limitadas a 8 MiB y las solicitudes tienen un tiempo de espera acotado.
Solo se conserva la cookie de sesión de ipTIME.
Las contraseñas, tokens, valores de sesión, claves privadas, PSK y campos similares se redactan recursivamente de la salida de MCP.
Una huella TLS opcional agrega fijación después de la validación normal del certificado; no hace válido un certificado autofirmado no confiable.

Trata los archivos de configuración del cliente MCP como secretos porque pueden contener la contraseña del router.

Comportamiento de CAPTCHA y sesión

Si el router solicita un CAPTCHA, iptime_login devuelve un error CAPTCHA_REQUIRED con información de desafío disponible. Abre la página de administración del router si es necesario, luego reintenta iptime_login con captcha_code.

Las sesiones expiradas se renuevan automáticamente una vez para operaciones de lectura. Las escrituras nunca se reintentan automáticamente después de una ambigüedad de autenticación o red.

Desarrollo

npm ci
npm run lint
npm test
npm run build

Para el modo de desarrollo:

npm run dev

El conjunto de pruebas utiliza routers simulados de bucle invertido y no requiere un dispositivo físico. No ejecutes pruebas de escritura contra un router de producción.

Archivos para agentes de IA

llms.txt proporciona un resumen compacto legible por máquina del proyecto y las herramientas.
AGENTS.md contiene reglas de contribución y seguridad del repositorio para agentes de codificación.
templates/AGENTS.md se puede copiar en un proyecto que deba usar este servidor MCP.
templates/CLAUDE.md proporciona una guía de uso equivalente para proyectos de Claude Code.

Estos archivos describen el flujo de trabajo real de las herramientas y las restricciones de seguridad; no contienen credenciales ni detalles locales del router.

iptime-mcp

Documentación

iptime-mcp

Características destacadas

Compatibilidad

Modelo de seguridad

Requisitos

Instalar desde npm

Instalar desde el código fuente

Configuración del cliente MCP

Codex / ChatGPT de escritorio

Claude Desktop

Claude Code

Cursor

Chat de agente de VS Code / GitHub Copilot Chat

GitHub Copilot CLI

Gemini CLI

Otros clientes MCP stdio

Variables de entorno

Un solo router

Múltiples routers

Herramientas MCP

Recursos MCP

Flujo de trabajo recomendado

Copia de seguridad, restauración y firmware

Seguridad de red

Comportamiento de CAPTCHA y sesión

Desarrollo

Archivos para agentes de IA

Licencia