OpenWRT-MCP

OpenWRT-MCP

Servidor MCP (Model Context Protocol) somente leitura para gerenciamento e diagnóstico de roteadores OpenWRT. Permite que assistentes de IA (Claude Desktop, LibreChat, Cline) observem e analisem um roteador OpenWRT sem qualquer acesso de escrita.

Requisitos

• Python 3.14+ (para uso local) ou Docker
• Roteador OpenWRT com SSH habilitado (Dropbear ou OpenSSH)
• Par de chaves SSH para autenticação

Início Rápido

1. Gerar Chave SSH

ssh-keygen -t ed25519 -f openwrt_id_ed25519 -C "openwrt-mcp"
ssh-copy-id -i openwrt_id_ed25519.pub root@192.168.0.1

2. Configurar

cp .env.example .env
# Edit .env with your OPENWRT_HOST and SSH key path

3. Executar com Docker

Opção A — com docker compose:

# After editing .env, for Docker add MCP_UNSAFE_PUBLIC_ACCESS_CONFIRMED=1 to .env
docker compose up -d

Opção B — com docker run simples:

docker run -d \
  --name openwrt-mcp \
  -p 9094:9094 \
  -p 9095:9095 \
  -p 9096:9096 \
  -e OPENWRT_HOST=192.168.0.1 \
  -e OPENWRT_SSH_KEY=/app/keys/openwrt_id_ed25519 \
  -e MCP_UNSAFE_PUBLIC_ACCESS_CONFIRMED=1 \
  -v $(pwd)/keys:/app/keys:ro \
  ghcr.io/paulomac1000/openwrt-mcp:latest

Construindo localmente:

git clone https://github.com/paulomac1000/openwrt-mcp.git
cd openwrt-mcp
docker build -t openwrt-mcp .
# Then run with the same docker run command above

4. Executar localmente (Python 3.14+)

pip install -e ".[dev]"
OPENWRT_HOST=192.168.0.1 OPENWRT_SSH_KEY=/path/to/key openwrt-mcp

Portas

Porta	Protocolo	Finalidade	Endpoint
9094	HTTP	Verificação de saúde	GET /health
9095	SSE	Transporte MCP (SSE)	/sse, /messages
9096	HTTP	API REST	/api/*

Verificar

# Health check
curl http://localhost:9094/health

# List all MCP tools
curl http://localhost:9096/api/tools

# Call a tool
curl -X POST http://localhost:9096/api/tools/get_router_info \
  -H "Content-Type: application/json" \
  -d '{}'

# Get tool manifest
curl http://localhost:9096/api/tools/get_router_info/manifest

Ferramentas Disponíveis (24)

As ferramentas são categorizadas por nível de risco: ferramentas [READ] são seguras — elas consultam o roteador sem efeitos colaterais. Ferramentas [WRITE] podem modificar o estado do roteador e exigem ENABLE_WRITE_OPERATIONS=1 em .env. Ferramentas [DESTRUCTIVE] são irreversíveis (reinicialização) e exigem confirmação explícita.

Categoria	Ferramenta	Risco	Descrição
Conexão	test_router_connection	READ	Verificar conectividade SSH
Sistema	get_router_info	READ	Informações da placa, memória, tempo de atividade, versão
	get_router_context	READ	Instantâneo de contexto unificado (sistema, wifi, DHCP, saúde)
	describe_router_capabilities	READ	Introspecção do servidor — ferramentas, manifestos, coletores
Rede	get_router_wifi_status	READ	Rádios WiFi, SSIDs, clientes conectados
	get_router_dhcp_leases	READ	Concessões DHCP ativas
	diagnose_router_connectivity	READ	Testes de ping, DNS e gateway
	ping_host	READ	Ping em um host específico
	traceroute_host	READ	Traceroute para um host
	nslookup_host	READ	Consulta DNS a partir do roteador
	wifi_scan	READ	Escaneamento de redes WiFi vizinhas
Segurança	get_router_firewall_rules	READ	Regras iptables / nftables / fw4
	read_router_uci_config	READ	Ler seções de configuração UCI
Diagnóstico	get_router_logs	READ	Logs recentes do sistema
	search_router_logs	READ	Busca filtrada em logs
Pacotes	list_router_packages	READ	Pacotes OPKG instalados
DHCP	get_dhcp_static_leases	READ	Reservas DHCP estáticas
	search_dhcp_logs	READ	Buscar eventos DHCP em logs
	get_device_dhcp_details	READ	Informações completas do dispositivo (concessão, reserva, logs)
Escrita	uci_set	WRITE	Definir um valor de configuração UCI
	uci_commit	WRITE	Confirmar alterações UCI permanentemente
	restart_interface	WRITE	Reiniciar uma interface de rede
	reload_network	WRITE	Recarregar serviços de rede
	reboot_device	DESTRUCTIVE	Reiniciar o roteador (irreversível)

Configuração

Toda a configuração é feita por variáveis de ambiente. Consulte .env.example para um modelo completo.

Obrigatório

Variável	Descrição	Exemplo
OPENWRT_HOST	Endereço IP do roteador	192.168.0.1
OPENWRT_SSH_KEY	Caminho para a chave privada SSH	/app/keys/openwrt_id_ed25519

Opcional

Variável	Padrão	Descrição
OPENWRT_PORT	22	Porta SSH
OPENWRT_USER	root	Nome de usuário SSH
MCP_SSE_PORT	9095	Porta de transporte MCP SSE
REST_API_PORT	9096	Porta da API REST
HEALTH_PORT	9094	Porta de verificação de saúde
SSH_TIMEOUT	30	Tempo limite de conexão SSH (segundos)
MCP_UNSAFE_PUBLIC_ACCESS_CONFIRMED	—	Defina como 1 para encaminhamento de porta Docker
ENABLE_WRITE_OPERATIONS	false	Defina como 1 para habilitar ferramentas de escrita (uci_set, reboot e outras)
OPENWRT_PASSWORD	None	Senha SSH (não recomendado — use chaves SSH)
ENABLE_AUDIT_LOGGING	true	Registrar todos os comandos executados
AUDIT_LOG_FILE	/app/log/openwrt_mcp.log	Caminho do log de auditoria
LOG_LEVEL	INFO	Nível de log
OPENWRT_KNOWN_HOSTS	—	Caminho para o arquivo known_hosts SSH para verificação da chave do host

Modelo de Segurança

• Somente leitura por padrão — Todos os comandos SSH estão na lista de permissões; operações de escrita (uci set, ifdown, ubus reboot) exigem ENABLE_WRITE_OPERATIONS=1
• Lista de permissões de comandos — Padrões explícitos somente leitura (ubus call, uci show, cat /proc/*, logread, ping e outros)
• Lista de permissões de comandos de escrita — Caminho execute_write() separado para operações de escrita (ifdown, ifup, uci set/commit, /etc/init.d/network, ubus reboot)
• Padrões bloqueados — rm, reboot, wget, curl, uci set (no caminho de leitura), metacaracteres de shell (;, |, &&, $ e outros)
• Autenticação baseada em chave — Login por senha desencorajado
• Verificação da chave do host SSH — Opcional via OPENWRT_KNOWN_HOSTS (defina o caminho do arquivo known_hosts)
• Registro de auditoria — Todos os comandos são registrados com carimbos de data/hora para responsabilização
• Vínculo localhost — Todas as portas vinculam a 127.0.0.1 por padrão; defina MCP_UNSAFE_PUBLIC_ACCESS_CONFIRMED=1 para Docker

Conformidade com Padrões

Este servidor segue dois padrões AI-First:

Padrão	Documento	Versão	Descrição
AFDS	docs_standards.md	v1.0	Estrutura de documentação, esquema frontmatter, linguagem controlada
MCP Core	mcp-server-standards.md	v1.1.0	Design de ferramentas, contratos de resposta, hierarquia de testes, segurança

Nível de conformidade: L3-ready (todas as regras L1-L3 atendidas; Matriz de Consistência de Risco aplicada por testes automatizados).

Testes

pip install -e ".[dev]"
pytest tests/unit/ tests/integration/ -q       # 268 tests (requires .env for integration)
pytest tests/unit/ --cov=openwrt_mcp -q         # 80%+ coverage
ruff check . && ruff format --check .           # lint
mypy src/openwrt_mcp/ --strict                  # type check
bandit -r src/openwrt_mcp/ -ll                  # security

Referência Rápida

Métrica	Valor
Python	3.14+ (Docker: 3.14)
Ferramentas	24 (19 READ + 4 WRITE + 1 DESTRUCTIVE)
Testes	296 (215 unit + 53 integration + 10 smoke + 18 e2e)
Cobertura	86%
Lint	0 erros (ruff + mypy --strict + bandit)
Docker	ghcr.io/paulomac1000/openwrt-mcp:latest
Padrões	AFDS v1.0 + MCP Core v1.1.0 — L2+
Licença	MIT

Licença

MIT