iptime-mcp

Um servidor MCP com proteção de segurança para gerenciar roteadores ipTIME em recursos de rede, Wi-Fi, VPN, NAT e sistema.

GitHubExperimente este MCPPatrocinado

Documentação

English | 한국어

iptime-mcp

Um servidor Model Context Protocol (MCP) com proteção de segurança para operar roteadores ipTIME sem abrir repetidamente o painel de administração web.

Ele pode inspecionar o estado do roteador, descobrir quais operações catalogadas um modelo e firmware específicos suportam e realizar alterações confirmadas em redes, Wi-Fi, NAT, firewall, VPN, DDNS, USB/NAS, sistema e recursos de automação.

Este é um projeto comunitário não oficial e não é afiliado à EFM Networks ou à ipTIME. As APIs do roteador dependem do firmware e não são publicadas como um contrato público estável.

Destaques

13 ferramentas MCP focadas em vez de centenas de ferramentas de nível superior
334 operações de roteador catalogadas: 171 leituras e 163 gravações
Verificações de capacidade em tempo de execução no iUX3 através do método api/has do roteador
Detecção para interfaces iUX3, Mobile iUX e CGI clássicas
Operações somente leitura podem ser executadas diretamente
Cada alteração no roteador usa um plano revisável e de curta duração, sem tokens de confirmação
Backup de configuração, planejamento de restauração e planejamento de atualização de firmware
Perfis de roteador único e multi-roteador
Redação de credenciais e valores de sessão
HTTP simples público bloqueado por padrão

O catálogo cobre administração, firmware, backup e restauração, WAN/LAN/DHCP/DNS, roteamento e comutação, wireless e EasyMesh, NAT e encaminhamento de portas, firewall, QoS, VPN, DDNS, serviços USB/NAS, rotinas, histórico, logs, varredura de hosts e Wake-on-LAN.

Compatibilidade

Interface	Suporte
iUX3	Usa `/cgi/service.cgi` JSON RPC e verifica cada método conhecido com `api/has`
Mobile iUX	Expõe apenas operações de leitura explicitamente mapeadas
CGI clássico	Expõe apenas operações de leitura explicitamente mapeadas

O catálogo fixo de operações é baseado em métodos observados em um aplicativo iUX3 enviado com o firmware 15.36.6. Um método que aparece no catálogo não significa que todo roteador o suporta. Sempre use iptime_capabilities para o roteador de destino antes de escolher uma operação.

O suporte legado é intencionalmente limitado a mapeamentos conhecidos e seguros para informações do sistema, leases e configuração de DHCP, encaminhamento de portas e Wake-on-LAN. Respostas legadas podem ser retornadas como texto bruto. Gravações legadas desconhecidas são rejeitadas.

Modelo de segurança

Alterações no roteador podem interromper o acesso à internet ou tornar a interface administrativa inacessível. iptime-mcp portanto separa leitura de gravação:

iptime_plan_change ou uma ferramenta de planejamento específica de arquivo cria um plano imutável sem alterar o roteador.
O plano informa a operação, parâmetros, estado atual quando disponível, risco e expiração.
iptime_apply_change aplica exatamente esse plano usando apenas seu plan_id; os usuários nunca precisam copiar um token APPLY <UUID>.

Uma solicitação específica para a mesma alteração é autorização suficiente. Os clientes devem perguntar mais uma vez em linguagem comum apenas quando um plano de risco crítico, como firmware, restauração, redefinição, credenciais ou formatação de armazenamento, não foi explicitamente autorizado. Os clientes MCP ainda podem mostrar seu prompt normal de aprovação de ferramenta destrutiva.

Os planos expiram após 10 minutos, são de uso único, incluem um digest de integridade e são serializados por roteador. Quando uma resposta de gravação é perdida, o servidor tenta uma releitura e não repete a gravação automaticamente. Os planos são mantidos em memória e desaparecem quando o processo MCP é reiniciado.

Requisitos

Node.js 22 ou posterior
Acesso de rede ao endpoint administrativo do roteador
Nome de usuário e senha de administrador ipTIME
Um cliente MCP com suporte a servidor stdio

Use um endereço LAN, um endereço VPN ou um endpoint HTTPS confiável sempre que possível.

Instalar a partir do npm

Use npx -y iptime-mcp como o comando stdio em um cliente MCP e defina IPTIME_ROUTER_URL, IPTIME_ROUTER_USERNAME e IPTIME_ROUTER_PASSWORD em sua configuração de ambiente privada. Mantenha a URL do roteador em uma LAN ou VPN confiável. Os exemplos abaixo mostram a configuração equivalente de instalação a partir da fonte para clientes que precisam de um caminho de script local.

Instalar a partir da fonte

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

O ponto de entrada executável é dist/server.js.

Para clientes que suportam um arquivo de ambiente ou diretório de trabalho configurável, crie um .env local primeiro:

cp .env.example .env

Preencha a URL do roteador, nome de usuário e senha. .env é ignorado pelo Git e deve permanecer local.

Configuração do cliente MCP

Use uma configuração de nível de usuário sempre que possível, pois as credenciais do roteador não devem ser commitadas em um projeto. Substitua /absolute/path/to/iptime-mcp em cada exemplo. No Windows, caminhos com barras normais, como C:/Users/name/iptime-mcp/dist/server.js, funcionam em JSON. Se um cliente de desktop não conseguir encontrar node, use o caminho absoluto relatado por which node no macOS/Linux ou where node no Windows.

Cliente	Configuração de nível de usuário
Codex / ChatGPT desktop	Configurações → Servidores MCP ou `~/.codex/config.toml`
Claude Desktop	Configurações → Desenvolvedor → Editar Config
Claude Code	`claude mcp add --scope user`
Cursor	`~/.cursor/mcp.json`
VS Code agent chat	MCP: Abrir Configuração do Usuário
GitHub Copilot CLI	`~/.copilot/mcp-config.json`
Gemini CLI	`~/.gemini/settings.json`

Codex / ChatGPT desktop

Adicione um servidor stdio em Configurações → Servidores MCP, ou adicione o seguinte a ~/.codex/config.toml. Substitua o caminho e as credenciais, salve e reinicie o 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, sua extensão IDE e o aplicativo de desktop ChatGPT compartilham a configuração MCP no mesmo host Codex. Consulte o guia oficial de configuração MCP para opções atuais do cliente.

Se você preferir o arquivo .env local, mantenha cwd e omita a tabela [mcp_servers.iptime.env].

Claude Desktop

Abra Configurações → Desenvolvedor → Editar Config, mescle a seguinte entrada iptime em claude_desktop_config.json, salve e reinicie completamente o Claude Desktop. Mantenha quaisquer outros servidores existentes no arquivo.

{
  "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 no compositor de chat após reiniciar. Consulte o guia oficial de MCP local do Claude Desktop.

Claude Code

Registre o servidor para todos os projetos com a CLI do 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

A opção final --transport vem intencionalmente após os valores de ambiente para que o analisador variádico --env não consuma o nome do servidor. A configuração com escopo de usuário é armazenada em ~/.claude.json. Consulte o guia oficial de MCP do Claude Code.

Cursor

Crie ou mescle ~/.cursor/mcp.json. Este exemplo lê o .env local ignorado criado acima:

{
  "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 o Cursor e verifique Configurações → Ferramentas e MCP. .cursor/mcp.json com escopo de projeto também é suportado, mas não coloque credenciais do roteador em um arquivo que possa ser commitado. Consulte o guia oficial de MCP do Cursor.

VS Code agent chat / GitHub Copilot Chat

Execute MCP: Abrir Configuração do Usuário na Paleta de Comandos e mescle esta configuração. O VS Code usa a chave de nível superior servers, não 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"
    }
  }
}

Inicie ou inspecione com MCP: Listar Servidores e aceite o prompt de confiança do servidor no primeiro uso. .vscode/mcp.json está disponível para configuração com escopo de espaço de trabalho, mas a configuração do usuário é mais segura para credenciais do roteador. Consulte a configuração oficial de MCP do VS Code e a referência de configuração.

GitHub Copilot CLI

O GitHub Copilot CLI não lê o .vscode/mcp.json do VS Code. Crie ou mescle ~/.copilot/mcp-config.json em vez disso:

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

O cwd configurado permite que iptime-mcp carregue o .env local. Verifique a conexão com copilot mcp list. .mcp.json e .github/mcp.json em nível de projeto também são suportados, mas nunca commite credenciais do roteador. Consulte o guia oficial de MCP do Copilot CLI.

Gemini CLI

Crie ou mescle ~/.gemini/settings.json:

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

O cwd configurado permite que o servidor carregue .env. Mantenha trust falso para que o Gemini continue perguntando antes das chamadas de ferramenta e execute gemini mcp list. Se a pasta atual não for confiável, execute gemini trust. O comando CLI usa como padrão o escopo do projeto; use --scope user ao registrar manualmente. Consulte o guia oficial de MCP do Gemini CLI.

Outros clientes MCP stdio

Use node como o comando, /absolute/path/to/iptime-mcp/dist/server.js como seu único argumento e passe as variáveis IPTIME_* de .env. Não presuma que todo cliente usa o mesmo wrapper JSON: por exemplo, o VS Code usa servers, enquanto Claude Desktop, Cursor, Copilot CLI e Gemini CLI usam mcpServers.

Variáveis de ambiente

Roteador único

Variável	Obrigatória	Padrão	Descrição
`IPTIME_ROUTER_URL`	Sim	—	URL base do roteador usando `http` ou `https`
`IPTIME_ROUTER_ID`	Não	`default`	Nome do perfil exposto como `router_id`
`IPTIME_ROUTER_USERNAME`	Para login	—	Nome de usuário administrador do roteador
`IPTIME_ROUTER_PASSWORD`	Para login	—	Senha do administrador do roteador
`IPTIME_ALLOW_INSECURE_REMOTE_HTTP`	Não	`false`	Permite HTTP simples quando o nome do host resolve para um endereço público
`IPTIME_TLS_FINGERPRINT`	Não	—	Impressão digital SHA-256 do certificado, com ou sem dois pontos, verificada além da validação TLS normal
`IPTIME_TIMEOUT_MS`	Não	`12000`	Tempo limite de solicitação, limitado a 1.000–60.000 ms

As credenciais não devem ser incorporadas em IPTIME_ROUTER_URL.

O servidor também carrega um arquivo .env de seu diretório de trabalho. Copie .env.example para .env apenas para uso local; .env e arquivos secretos relacionados são ignorados pelo Git.

Múltiplos roteadores

Defina IPTIME_ROUTERS como um array JSON. Use username_env e password_env para que o JSON contenha nomes de variáveis de ambiente em vez de credenciais:

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

Quando um roteador está configurado, router_id pode ser omitido. Com vários roteadores, passe o router_id de destino para as ferramentas do roteador.

Ferramentas MCP

Ferramenta	Finalidade
`iptime_status`	Detecta a interface, autentica quando existem credenciais e lê o status do produto/sistema
`iptime_login`	Faz login com credenciais do ambiente MCP; opcionalmente envia uma resposta CAPTCHA
`iptime_logout`	Encerra a sessão administrativa atual do roteador
`iptime_capabilities`	Verifica operações catalogadas em relação ao modelo e firmware de destino
`iptime_list_operations`	Lista o catálogo de operações local e auditável por domínio ou modo
`iptime_read`	Executa uma operação de catálogo somente leitura
`iptime_backup_config`	Salva um novo arquivo de backup `.config` sem sobrescrever um arquivo existente
`iptime_plan_change`	Cria um plano genérico de alteração do roteador sem aplicá-lo
`iptime_plan_firmware_upgrade`	Gera hash de uma imagem `.bin` local e cria um plano de atualização de risco crítico
`iptime_plan_config_restore`	Gera hash de um backup `.config` local e cria um plano de restauração de risco crítico
`iptime_apply_change`	Aplica um plano pendente por ID; nenhum token de confirmação é necessário
`iptime_cancel_change`	Cancela um plano pendente
`iptime_list_plans`	Lista planos pendentes e concluídos em memória

Recursos MCP

URI	Conteúdo
`iptime://configuration`	Perfis de roteador configurados com credenciais omitidas
`iptime://operations`	Catálogo completo de operações, domínios, modos, riscos e dicas de parâmetros

Fluxo de trabalho recomendado

Chame iptime_status para detectar o roteador e estabelecer uma sessão.
Chame iptime_capabilities, opcionalmente filtrado por um domínio como wireless, network, vpn ou usb.
Use iptime_list_operations para encontrar a operação exata e a dica de parâmetro.
Execute leituras com iptime_read.
Para uma alteração, crie um plano e mostre seu risco, parâmetros, estado anterior e expiração ao usuário.
Se o plano corresponder à solicitação específica do usuário, aplique-o sem pedir que ele repita um token ou ID de plano. Pergunte uma vez em linguagem natural apenas para uma alteração de risco crítico que não foi explicitamente autorizada.
Se o resultado for relatado como desconhecido, inspecione o estado de verificação retornado antes de fazer qualquer outra coisa.

Operações de leitura úteis incluem:

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

Alguns métodos exigem um escalar, array ou objeto em vez de um objeto vazio. Os campos paramsHint e defaultParams do catálogo descrevem convenções conhecidas. Por exemplo, a listagem de canais Wi-Fi precisa de uma banda como "2g" ou "5g", e o status do DDNS precisa do hostname configurado.

Backup, restauração e firmware

iptime_backup_config:

exige um destino que termine em .config
cria diretórios pai quando necessário
recusa sobrescrever um arquivo existente
grava com permissões somente do proprietário (0600)
rejeita backups vazios e arquivos maiores que 32 MiB

Backups de configuração podem conter configurações de rede privadas e segredos. *.config é ignorado pelo Git e nunca deve ser commitado.

Os planos de firmware e restauração registram o tamanho do arquivo e o hash SHA-256 e verificam o arquivo novamente imediatamente antes do upload. Imagens de firmware devem terminar em .bin; backups de configuração devem terminar em .config. Uma imagem de firmware não é validada quanto à compatibilidade com o modelo do roteador, portanto obtenha a imagem correta para o modelo exato e revise o plano de risco crítico com cuidado.

Segurança de rede

HTTP simples em endereço público é rejeitado, a menos que IPTIME_ALLOW_INSECURE_REMOTE_HTTP=true.
Ativar essa substituição pode expor a senha do administrador e o cookie de sessão. Use-a apenas por meio de um túnel privado confiável quando HTTPS for impossível.
Redirecionamentos e construção de endpoints entre origens são bloqueados.
As respostas são limitadas a 8 MiB e as solicitações têm um tempo limite limitado.
Apenas o cookie de sessão do ipTIME é retido.
Senhas, tokens, valores de sessão, chaves privadas, PSKs e campos semelhantes são redigidos recursivamente da saída do MCP.
Uma impressão digital TLS opcional adiciona fixação após a validação normal do certificado; ela não torna válido um certificado autoassinado não confiável.

Trate os arquivos de configuração do cliente MCP como segredos, pois eles podem conter a senha do roteador.

Comportamento de CAPTCHA e sessão

Se o roteador solicitar um CAPTCHA, iptime_login retorna um erro CAPTCHA_REQUIRED com informações de desafio disponíveis. Abra a página de administração do roteador se necessário e tente novamente iptime_login com captcha_code.

Sessões expiradas são renovadas automaticamente uma vez para operações de leitura. Gravações nunca são repetidas automaticamente após uma ambiguidade de autenticação ou rede.

Desenvolvimento

npm ci
npm run lint
npm test
npm run build

Para o modo de desenvolvimento:

npm run dev

A suíte de testes usa roteadores simulados de loopback e não exige um dispositivo físico. Não execute testes de gravação contra um roteador de produção.

Arquivos para agentes de IA

llms.txt fornece um resumo compacto do projeto e das ferramentas legível por máquina.
AGENTS.md contém regras de contribuição e segurança do repositório para agentes de codificação.
templates/AGENTS.md pode ser copiado para um projeto que deva usar este servidor MCP.
templates/CLAUDE.md fornece orientação de uso equivalente para projetos Claude Code.

Esses arquivos descrevem o fluxo de trabalho real das ferramentas e as restrições de segurança; eles não contêm credenciais nem detalhes locais do roteador.

iptime-mcp

Documentação

iptime-mcp

Destaques

Compatibilidade

Modelo de segurança

Requisitos

Instalar a partir do npm

Instalar a partir da fonte

Configuração do cliente MCP

Codex / ChatGPT desktop

Claude Desktop

Claude Code

Cursor

VS Code agent chat / GitHub Copilot Chat

GitHub Copilot CLI

Gemini CLI

Outros clientes MCP stdio

Variáveis de ambiente

Roteador único

Múltiplos roteadores

Ferramentas MCP

Recursos MCP

Fluxo de trabalho recomendado

Backup, restauração e firmware

Segurança de rede

Comportamento de CAPTCHA e sessão

Desenvolvimento

Arquivos para agentes de IA

Licença