mikrotik-mcp

A Bun-native MCP server that turns one or more MikroTik routers into 706 tools your AI can drive.
Firewall · routing · DHCP/DNS · wireless · QoS · and a complete VPN suite — over SSH, with transactional Safe Mode.

@usex/mikrotik-mcp exposes MikroTik RouterOS as 706 Model Context Protocol
tools across 111 modules, so an AI client (Claude Desktop, Claude Code, any MCP
client) can read and configure your router in plain language. It speaks to the
device over SSH — no agent, no API package to install on RouterOS — runs on
Bun, and validates every tool call against a Zod schema.

Every tool is risk-annotated (read / write / destructive) so clients can gate
what runs, and risky changes can be wrapped in Safe Mode — RouterOS holds them
in memory and auto-reverts if your session drops, so you can't lock yourself out.

// claude_desktop_config.json
{
  "mcpServers": {
    "mikrotik": {
      "command": "mikrotik-mcp",
      "env": {
        "MIKROTIK_HOST": "192.168.88.1",
        "MIKROTIK_USERNAME": "admin",
        "MIKROTIK_PASSWORD": "your-password",
      },
    },
  },
}

"Show me the firewall input chain, then block SSH from the WAN under safe mode."
"Build an IKEv2 site-to-site tunnel to 203.0.113.5 for 192.168.20.0/24."
"Why can't VLAN 50 reach the internet?"

Why it's different

• 🧰 Breadth — 706 tools covering the whole device: L2 (bridge, VLAN, wireless,
  PoE), L3 (addressing, routing, DHCP, DNS), security (firewall, NAT, address-lists,
  certificates), QoS (queues), and system ops (users, logs, backups, scheduler).
• 🔐 A complete VPN suite — WireGuard, IPsec (IKEv1/IKEv2), L2TP, PPTP, SSTP,
  OpenVPN, plus GRE/IPIP/EoIP/VXLAN tunnels. With a choose-vpn-solution prompt
  that picks the right one for you. See the VPN guide.
• 🛟 Safe Mode — a real transactional window (enable_safe_mode →
  changes → commit_safe_mode/rollback_safe_mode) backed by a persistent SSH
  session. Auto-reverts on disconnect.
• 🚦 Risk-annotated tools — readOnlyHint / destructiveHint let clients
  auto-approve reads and prompt on writes.
• 🧱 Injection-safe by construction — a command builder quotes/escapes every
  value, so a hostname like LAN; /system reset can never split into a second
  command.
• 🖧 Multiple devices — define named routers and the AI targets one per call
  (a validated device argument). Configure both ends of a tunnel from one
  conversation. See docs/multi-device.md.
• 🤖 Guided prompts — 9 built-in workflows (harden, diagnose, guest Wi-Fi, VPNs,
  cross-device tunnels, backup & document) that turn an intent into tool calls.

Quickstart

# 1. Install (requires Bun ≥ 1.3 — https://bun.sh)
bun add -g @usex/mikrotik-mcp

# 2. Point it at your router and verify SSH connectivity
MIKROTIK_HOST=192.168.88.1 MIKROTIK_USERNAME=admin MIKROTIK_PASSWORD=•••• \
  mikrotik-mcp auth-check

# 3. List the catalog (name · risk · title)
mikrotik-mcp tools

# 4. Run it (stdio by default — wire it into your MCP client)
mikrotik-mcp serve

Try it without an AI client — open the official MCP Inspector
against the server (from source):

bun run inspect        # opens the Inspector UI to browse/run all 706 tools

Prefer SSH keys over a password? Point the server at a key file instead — and
add a passphrase if the key is encrypted:

MIKROTIK_HOST=192.168.88.1 MIKROTIK_USERNAME=admin \
MIKROTIK_KEY_FILENAME=~/.ssh/id_ed25519 \
MIKROTIK_KEY_PASSPHRASE=•••• \
  mikrotik-mcp auth-check     # prints "Auth mode: SSH key"

The key (file via --key-filename or inline PEM via --private-key) takes
precedence over a password. Full configuration reference:
docs/configuration.md.

From source

git clone https://github.com/ali-master/mikrotik-mcp && cd mikrotik-mcp
bun install
bun run start            # serve from source
bun run build            # bundle to dist/

The tool catalog

706 tools across 111 modules. Full, always-current reference (parameters +
risk per tool) is generated from source: docs/tools-reference.md.

VPN & tunneling — expert coverage

Every MikroTik VPN technology, modeled the way RouterOS actually layers them (the
PPP-based VPNs share one /ppp backend for users and addressing):

Not sure which? Invoke the choose-vpn-solution prompt and the server
recommends one and outlines the build. Details: docs/vpn-guide.md.

Manage multiple devices

Give each router a name and the AI can drive them all from one conversation —
exactly what you need to set up a tunnel between two MikroTiks and test it from
both ends. Point the server at a JSON file (or MIKROTIK_DEVICES):

// devices.json
{
  "defaultDevice": "site-a",
  "devices": {
    "site-a": { "host": "203.0.113.10", "username": "admin", "keyFilename": "/keys/site-a" },
    "site-b": { "host": "198.51.100.20", "username": "admin", "password": "••••" },
  },
}

mikrotik-mcp serve --config ./devices.json
mikrotik-mcp devices        # site-a (default) · site-b
mikrotik-mcp auth-check     # probes every device

When more than one device is configured, every tool gains an optional device
argument (a validated enum of your names); omit it to use the default. The AI
discovers names with list_mikrotik_devices, and Safe Mode is per-device so
each router commits independently. The setup-tunnel-between-sites prompt
drives the whole both-ends flow. Full guide: docs/multi-device.md.

// the AI calls a tool against a specific router:
// create_wireguard_interface { "device": "site-a", "name": "wg-to-b", "listen_port": 13231 }

Built-in prompts

MCP prompts are one-click guided workflows. This server ships 9 — authored as
Markdown in prompts/, so you can edit or add your own without
touching code:

harden-router · diagnose-connectivity · setup-guest-wifi ·
choose-vpn-solution · setup-wireguard-vpn · setup-ipsec-site-to-site ·
setup-l2tp-ipsec-roadwarrior · setup-tunnel-between-sites · backup-and-document

See docs/prompts.md.

Transports

HTTP transports expose POST /mcp and a GET /health check, with DNS-rebinding
protection that reconciles with your bind host automatically. See
docs/transports.md.

Safe Mode

enable_safe_mode → (make changes) → commit_safe_mode    # persist
                                   → rollback_safe_mode  # discard

While active, every change is held in memory; if the SSH session drops (e.g. a
firewall rule that locks you out), RouterOS reverts everything automatically.
Commands issued during the window are routed through the same persistent session.
See docs/safe-mode.md.

Configuration

Connection and transport settings come from MIKROTIK_* env vars or matching CLI
flags (highest precedence last: defaults → env → flags).

Full table (incl. HTTP host, allow-lists, timeouts, MIKROTIK_LOG_LEVEL):
docs/configuration.md.

Observability dashboard (optional)

A localhost-only web dashboard that intercepts every tool call the LLM makes
— live feed of inputs/outputs (secrets redacted), latency percentiles, error
rate and per-tool/risk/device analytics — persisted to a Bun-native SQLite store
and served on its own port alongside any transport:

mikrotik-mcp serve --dashboard          # → http://127.0.0.1:9090

See docs/observability.md.

Beyond the catalog

On top of the per-scope tools, the server ships higher-level workflows:

• Change Plan & Dry-Run — preview intended commands as
  a terraform-style plan (risk-scored, lock-out-aware, safely reordered), then
  apply_plan runs them under Safe Mode, shows the exact /export diff, and
  commits only if the device is still reachable (auto-reverts a lock-out).
• Config Snapshots — store /export snapshots on
  the host and time-travel diff any two, or one against the live device.
• Firewall Audit — firewall_audit finds shadowed,
  overly-broad, missing-default-drop, duplicate and dead rules, risk-scored, with
  one-click fixes in MCP App hosts.
• Packet Capture Studio — stream mirrored packets to
  the host as TZSP, decode them live in the dashboard, and export .pcap.
• Discovery — bun run discover lists MikroTik devices on
  the LAN by MAC (MNDP); the dashboard draws a live topology map.
• Config Studio — edit the config JSON in the
  dashboard with autocomplete, validation, and safe-apply auto-rollback.

Schemas

schemas/ ships machine-readable JSON Schemas, generated from the TypeScript
source (bun run gen:schemas) so they can never drift:

• schemas/tool-catalog.json — every tool with risk, description, and input schema
• schemas/tools/<name>.json — per-tool input schema
• schemas/config.schema.json — the runtime configuration

Documentation

Development

bun run test:types   # tsc --noEmit
bun test             # unit tests
bun run gen          # regenerate schemas/ + docs/tools-reference.md from source
bun run build        # bundle to dist/

See docs/development.md and CONTRIBUTING.md.

Security

Talks to RouterOS over SSH using credentials you supply; nothing is sent anywhere
else. Tool values are quoted/escaped to prevent console-command injection.
Destructive and dangerous tools are annotated so clients can require confirmation,
and a plaintext-password-in-a-container warning nudges you toward key files or
secrets. Details: docs/security.md. Only point this at
devices you're authorized to manage.

License

MIT. Reuse freely. No warranty.

Made with ❤️ by Ali Torki