mikrotik-mcp

@usex/mikrotik-mcp exposes MikroTik RouterOS as 310 Model Context Protocol tools across 31 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 — 310 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.

• 🔁 Drop-in for the Python server — the MIKROTIK_* environment variables are byte-for-byte compatible; swap the binary, keep your config.

• 🤖 Guided prompts — 8 built-in workflows (harden, diagnose, guest Wi-Fi, VPNs, backup & document) that turn an intent into the right sequence of tool calls.

Related MCP server: RouterOS MCP Server

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

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

310 tools across 31 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.

Built-in prompts

MCP prompts are one-click guided workflows. This server ships 8 — 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 · 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.

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 — all 310 tools with risk, description, and input schema

• schemas/tools/<name>.json — per-tool input schema

• schemas/config.schema.json — the runtime configuration

Migrating from the Python server

This is a from-scratch rewrite of mcp-server-mikrotik in Bun + TypeScript. All 169 original tools are ported 1:1 (same names, same parameters), plus 141 new ones (the full VPN suite, system/network tools, bridge, address-lists, scheduler, certificates, IP services). Because the MIKROTIK_* environment variables are identical, migration is usually just swapping the command. The legacy Python source remains in mikrotik-mcp/ for reference.

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.