AsusWRT MCP Server

Servidor MCP AsusWRT

mcp-name: io.github.teefloo/asuswrt-mcp

Servidor Model Context Protocol (MCP) para administração segura e controlada de roteadores AsusWRT e AsusWRT-Merlin via SSH.

Visão Geral

Este servidor MCP fornece aos assistentes de IA (como Claude, Cursor, etc.) uma interface segura para monitorar e gerenciar roteadores AsusWRT. Ele opera exclusivamente via SSH usando operações em lista de permissões—sem execução arbitrária de comandos, sem modificações de firmware e sem redefinições de fábrica.

Recursos

Monitoramento Somente Leitura (42 ferramentas)

Categoria	Ferramentas
Identidade e Saúde	Modelo do roteador, versão do firmware, tempo de atividade, carga, memória
Rede	Detalhes LAN/WAN, configuração de DNS, status IPv6, tabela de roteamento
Clientes	Clientes conectados, concessões DHCP, vizinhos ARP
Sem Fio	Status do rádio, SSIDs, redes de convidados, contagem de clientes por banda
Serviços	Processos em execução, portas abertas, tarefas cron
Armazenamento	Dispositivos USB, montagens, partições, uso do sistema de arquivos
Segurança	UPnP, DDNS, status Samba, uso de conntrack
VPN	Servidor OpenVPN, WireGuard, perfis de cliente VPN
Administração	Portas de administração web, configurações de acesso SSH/telnet
Diagnóstico	Diagnóstico TCP/banner/auth SSH, instantâneo de configuração

Ferramentas de Mutação (com proteções de segurança)

Todas as ferramentas de mutação exigem:

• Parâmetro confirm: true
• Variável de ambiente ASUSWRT_ALLOW_MUTATIONS=true
• Suporte para dry_run: true para visualizar alterações

Ferramenta	Descrição
asuswrt_restart_service	Reiniciar serviços em lista de permissões (httpd, firewall, wireless, dnsmasq, etc.)
asuswrt_dhcp_server	Ativar/desativar servidor DHCP
asuswrt_upnp	Ativar/desativar UPnP
asuswrt_radio	Ativar/desativar bandas de rádio Wi-Fi
asuswrt_guest_wifi	Ativar/desativar Wi-Fi de convidados
asuswrt_guest_lan_access	Alternar acesso LAN para Wi-Fi de convidados
asuswrt_port_forwarding	Listar, adicionar, remover, ativar/desativar regras de encaminhamento de porta
asuswrt_vpn_server	Ativar/desativar servidor OpenVPN
asuswrt_parental_access	Listar, bloquear, desbloquear, remover regras de controle parental
asuswrt_parental_block_all	Alternar modo de bloqueio total
asuswrt_dhcp_reservation	Listar, adicionar, remover reservas estáticas DHCP

Modelo de Segurança

• Sem SSH arbitrário: Apenas comandos em lista de permissões são executados via chamadas NVRAM e de serviço
• Sem operações de firmware: Sem flash, redefinição ou acesso ao bootloader
• Redação de segredos: Senhas e dados sensíveis nunca são expostos nas respostas das ferramentas
• Suporte a simulação: Toda mutação pode ser visualizada antes de ser aplicada
• Confirmação necessária: Mutações exigem confirm=True explícito
• Transporte somente SSH: Sem exposição da API web do roteador

Pré-requisitos

• Python 3.11+
• Um roteador AsusWRT ou AsusWRT-Merlin com acesso SSH habilitado
• Conectividade de rede do cliente MCP ao roteador

Instalação

1. Clonar e configurar

git clone https://github.com/Teeflo/asuswrt-mcp.git
cd asuswrt-mcp

# Create virtual environment
python -m venv .venv

# Activate (Linux/macOS)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

# Install dependencies
pip install -e .

2. Configurar ambiente

# Copy example configuration
cp .env.example .env

# Edit with your router credentials
# Use your favorite editor:
notepad .env        # Windows
nano .env           # Linux/macOS

3. Configurar .env

# Required: Router connection
ASUSWRT_HOST=192.168.1.1
ASUSWRT_SSH_USERNAME=admin
ASUSWRT_SSH_PASSWORD=your_password

# Optional: SSH key authentication
# ASUSWRT_SSH_KEY_FILE=~/.ssh/id_rsa

# Optional: Enable mutations (disabled by default)
# ASUSWRT_ALLOW_MUTATIONS=true

# Optional: Connection settings
# ASUSWRT_SSH_PORT=22
# ASUSWRT_TIMEOUT_SECONDS=10

Uso

Executar o servidor MCP

# Standard stdio mode
python -m asuswrt_mcp.server

# Or use the entry point
asuswrt-mcp

Configurar no Claude Desktop / Cursor

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "asuswrt-mcp": {
      "command": "C:\\path\\to\\asuswrt-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "asuswrt_mcp.server"],
      "env": {
        "ASUSWRT_HOST": "192.168.1.1",
        "ASUSWRT_SSH_USERNAME": "admin",
        "ASUSWRT_SSH_PASSWORD": "your_password"
      }
    }
  }
}

Usando com npx Inspector (desenvolvimento)

npx @modelcontextprotocol/inspector python -m asuswrt_mcp.server

Desenvolvimento

Executar testes

pip install -e ".[dev]"
pytest

Executar com testes de integração com roteador real

ASUSWRT_TEST_ROUTER=1 pytest

Estrutura do Projeto

asuswrt-mcp/
├── src/asuswrt_mcp/
│   ├── server.py          # FastMCP entrypoint & tool definitions
│   ├── service.py         # Business logic & router operations
│   ├── config.py          # Settings management
│   ├── clients/
│   │   └── ssh.py         # SSH client wrapper
│   ├── nvram.py           # NVRAM parsing utilities
│   ├── ssh_parsers.py     # Output parsers for SSH commands
│   ├── security.py        # Mutation guards & redaction
│   ├── validators.py      # Input validation
│   ├── responses.py       # Tool response formatting
│   ├── errors.py          # Custom exceptions
│   └── serialization.py   # Safe serialization
├── tests/                 # Test suite (69 tests)
├── .env.example           # Example configuration
├── pyproject.toml         # Project metadata
└── README.md              # This file

Licença

Licença MIT - consulte LICENSE para detalhes.

Agradecimentos

• asusrouter pela biblioteca Python subjacente
• MCP pela especificação do protocolo
• AsusWRT-Merlin pelo firmware