MikroTik MCP

mikrotik-mcp

Un servidor MCP (Model Context Protocol) para gestionar flotas de dispositivos MikroTik RouterOS desde asistentes de IA como Claude.

Expone 65 herramientas que cubren administración del sistema, interfaces, bridging, IP, firewall, DHCP/DNS, PPP, monitorización y diagnóstico — todo ejecutado a través de la API REST de RouterOS, reservando SSH para la ejecución libre de ros-command. Las credenciales de los dispositivos nunca pasan por el modelo: se resuelven desde una bóveda KeePass en tiempo de ejecución.

Aspectos destacados

• Diseñado para flotas — cada herramienta acepta un target de un único ID de dispositivo, una lista separada por comas (R1,R2,R3) o all. Los comandos se distribuyen en paralelo y devuelven resultados por dispositivo; un dispositivo inalcanzable nunca hace fallar el lote.
• Transporte REST primero — JSON estructurado desde la API REST de RouterOS (RouterOS v7.1+), sin análisis frágil de terminal. SSH se usa únicamente para la vía de escape ros-command.
• Credenciales respaldadas por KeePass — los dispositivos se enumeran desde un grupo de la bóveda .kdbx. El LLM solo ve identificadores de dispositivo, nunca contraseñas.
• Modo de solo lectura impuesto — READ_ONLY=true retiene las 14 herramientas de escritura/ejecución y diagnóstico activo a nivel de protocolo, exponiendo únicamente las 51 herramientas de consulta de estado. Ideal para acceso de agentes de solo monitorización. La aprobación de llamadas de escritura individuales se deja al cliente MCP, que es donde realmente se puede aplicar (ver Operaciones de escritura y aprobación).
• Dos transportes MCP — stdio para clientes locales (Claude Desktop, Claude Code) y Streamable HTTP (con respaldo SSE heredado) para un servidor de equipo compartido.

Resumen de herramientas

Área	Ejemplos
Sistema	identidad, reloj, salud, hardware, paquetes, licencia, historial, nota, certificados, registro, archivos
Interfaces y bridging	lista/estadísticas de interfaces, habilitar/deshabilitar, listas de interfaces, bridges, puertos, VLANs, tabla MAC, vecinos
IP	direcciones, ARP, rutas, pools, ajustes IP, servicios IP
Firewall	filtro, NAT, mangle, listas de direcciones, seguimiento de conexiones, RADIUS
DHCP y DNS	cliente/servidor DHCP, concesiones, redes, ajustes DNS, entradas estáticas
PPP y usuarios	perfiles, secretos, sesiones activas, AAA, usuarios del sistema, programador, scripts, reglas de registro
Servicios	NTP, SNMP, reinicio/apagado
Diagnóstico	ping, traceroute, prueba de ancho de banda, torch, sniffer de paquetes, perfil, netwatch, fetch, prueba de velocidad, WoL, escaneo MAC/IP, generador de tráfico
Flota y vía de escape	device-list, setup-new-device, ros-command (CLI arbitrario sobre SSH)

Inicio rápido

1. Preparar la bóveda de credenciales

Crea una bóveda KeePass (p. ej. config/vault.kdbx) con una entrada por dispositivo dentro de un grupo (por defecto: mikrotik):

• Título → ID del dispositivo (cómo te referirás al dispositivo en los prompts)
• Nombre de usuario / Contraseña → credenciales de RouterOS
• URL → nombre de host o IP del dispositivo

2. Ejecutar con Docker (servidor HTTP compartido)

Usando la imagen precompilada:

docker run -d -p 8000:8000 \
  -v ./config:/config:ro \
  -e KEEPASS_PASSWORD='…' \
  ghcr.io/vesact/mikrotik-mcp:latest   # serves MCP on http://localhost:8000/mcp

O compilar desde el código fuente:

cp .env.example .env        # set KEEPASS_PASSWORD at minimum
docker compose up -d

3. O ejecutar localmente sobre stdio (Claude Desktop / Claude Code)

npm ci && npm run build

{
  "mcpServers": {
    "mikrotik": {
      "command": "node",
      "args": ["/path/to/mikrotik-mcp/dist/index.js"],
      "env": {
        "KEEPASS_PATH": "/path/to/vault.kdbx",
        "KEEPASS_PASSWORD": "…"
      }
    }
  }
}

Luego pregunta cosas como:

"¿Cuál es la versión de RouterOS en toda la flota?" "Muestra las concesiones DHCP en router-01." "Añade un filtro de firewall en R1,R2."

Configuración

Toda la configuración se realiza mediante variables de entorno (ver .env.example):

Variable	Por defecto	Propósito
KEEPASS_PASSWORD	— (requerida)	Contraseña maestra de la bóveda KeePass
KEEPASS_PATH	/config/keepass.kdbx	Ruta al archivo de bóveda .kdbx
KEEPASS_GROUP	mikrotik	Grupo de la bóveda del que enumerar dispositivos
ROUTEROS_REST_PORT	443	Puerto de la API REST en los dispositivos de destino
ROUTEROS_REST_SCHEME	https	https o http
ROUTEROS_TIMEOUT_MS	10000	Tiempo de espera de las solicitudes REST
SSH_TIMEOUT_MS	10000	Tiempo de espera SSH por comando (ros-command)
ROUTEROS_SETUP_PORT	80 (sin cambios)	Puerto www de destino al hacer arranque mediante setup-new-device
MCP_TRANSPORT	stdio (http en la imagen Docker)	Transporte MCP
MCP_HTTP_PORT	3000 (8000 en la imagen Docker)	Puerto de escucha HTTP
MCP_HOST	0.0.0.0	Dirección de enlace HTTP
READ_ONLY	false	Exponer solo herramientas de consulta de estado de solo lectura

Modo de solo lectura

Con READ_ONLY=true (también acepta 1/yes/on), el servidor expone solo las 51 herramientas de solo lectura. ros-command, setup-new-device y todos los diagnósticos activos (ping, traceroute, torch, prueba de ancho de banda, escaneos, …) se omiten — mutan el estado o generan tráfico de red. La lista de permitidos es explícita, por lo que las herramientas añadidas en el futuro se omiten hasta que se clasifiquen deliberadamente.

Operaciones de escritura y aprobación

El servidor no implementa su propio paso de confirmación para escrituras. Las herramientas de escritura se ejecutan en la primera llamada, y ros-command en particular ejecuta lo que se le dé, tal cual, en cada dispositivo que coincida con target.

Aprobar llamadas individuales es tarea del cliente MCP — es la capa que realmente puede aplicar una decisión y limitarla por agente:

• Claude Code — modos de permiso más reglas allow/ask/deny, p. ej. "deny": ["mcp__mikrotik__ros-command"] o una regla ask para todo el servidor, en .claude/settings.json.
• Claude Desktop y otros hosts — prompts de aprobación por herramienta, mantenidos habilitados para este servidor.

ros-command lleva los annotations de MCP (readOnlyHint: false, destructiveHint: true) para que los clientes puedan clasificarlo sin analizar su descripción.

Quedan dos controles en el lado del servidor, porque son aplicación de reglas y no instrucciones:

• READ_ONLY=true — las herramientas nunca se registran, por lo que ninguna configuración del cliente puede invocarlas.
• Las credenciales de RouterOS en la bóveda — una cuenta de dispositivo con permisos restringidos limita lo que cualquier comando aprobado puede hacer.

Requisitos

• Node.js ≥ 22 (o Docker)
• RouterOS v7.1+ con la API REST habilitada (servicio www-ssl o www) en los dispositivos gestionados
• SSH habilitado en los dispositivos solo si usas ros-command o setup-new-device

Desarrollo

npm ci
npm run build          # TypeScript → dist/
npm test               # unit tests (Vitest, no hardware needed)
npm run check          # lint + format check (Biome)
npm run check:fix      # apply Biome's fixes and formatting
npm run test:integration   # integration tests against real hardware (see .env.test.example)

Las pruebas unitarias se ejecutan contra fixtures, incluyendo una bóveda de prueba incluida en el repositorio (tests/fixtures/test-vault.kdbx, contraseña test-password-123 — solo credenciales falsas). Las pruebas de integración requieren un dispositivo RouterOS accesible y se configuran mediante .env.test.

Arquitectura

MCP client (Claude, …)
   │  stdio / Streamable HTTP
   ▼
mikrotik-mcp server ──► KeePass vault (device inventory + credentials)
   │
   │  fan-out: target = "R1" | "R1,R2" | "all"   (parallel, per-device results)
   ▼
RouterOS REST API (all tools)  /  SSH (ros-command only)

El documento completo de arquitectura está en docs/architecture.md, y los requisitos originales del producto en docs/prd.md.

Contribuciones

Ver CONTRIBUTING.md. Problemas de seguridad: ver SECURITY.md.

Licencia

Publicado bajo la Licencia Apache 2.0.

Copyright 2026 Actemium Schweiz AG — una empresa de VINCI Energies.

MikroTik y RouterOS son marcas comerciales de Mikrotīkls SIA. Este proyecto no está afiliado ni respaldado por MikroTik.