mikrotik-mcp

@usex/mikrotik-mcp exposes MikroTik RouterOS as 819 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 — 819 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.

• 🪜 SSH jump hosts — reach a router with no exposed port by tunnelling through another via jumpVia (ProxyJump/bastion) — commands, Safe Mode and file upload all ride the hop. No new WAN port.

• ⚡ Connection pooling — one persistent SSH session per device, reused across tool calls. Saves ~200-500 ms handshake per command (double through jump hosts). Idle connections auto-close after 30 s.

• 🤖 Guided prompts — 9 built-in workflows (harden, diagnose, guest Wi-Fi, VPNs, cross-device tunnels, backup & document) that turn an intent into 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

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 819 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/mikrotik-mcp/mikrotik-mcp && cd mikrotik-mcp
bun install
bun run start            # serve from source
bun run build            # bundle to dist/

As an MCP Bundle (.mcpb)

A one-click install for Claude Desktop and other MCPB hosts — no Bun, Node or npm needed on the machine, and the router credentials are entered in the host's UI rather than a shell.

bun run build:mcp                       # bundle for this machine
bun run build:mcp --target linux-x64    # or one specific target
bun run build:mcp:all                   # every target

Bundles land in dist-mcpb/ as mikrotik-mcp-<version>-<platform>-<arch>.mcpb. Open one with your MCPB host (on Claude Desktop, drag it onto Settings → Extensions) and fill in the router address and credentials it prompts for.

Because the server is Bun-native — bun:sqlite, Bun.serve, Bun.S3Client, and @tikoci/centrs, which ships raw TypeScript — it cannot run on the Node runtime an MCPB host provides. Each bundle therefore vendors the Bun binary it was built against and runs runtime/bun dist/cli.js serve, so every subsystem (MAC-Telnet, the dashboard, S3 backups) behaves exactly as it does from source. That costs about 60 MB per bundle and makes each one platform-specific — hence one artifact per platform/arch rather than a single universal file.

The build stages the bundle, validates the manifest, and drives the staged server over stdio (initialize + tools/list, asserting the tool count matches the manifest) before packing. Pass --no-smoke to skip that last check.

The tool catalog

819 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 }

Behind a bastion? Reach a router with no exposed SSH port by jumping through another (OpenSSH-style ProxyJump) — jumpVia names a configured device to tunnel through; commands, Safe Mode and SFTP upload all ride the hop:

"home-ax3": { "host": "10.10.30.100", "username": "admin", "jumpVia": "hex" }

The bastion router needs SSH TCP forwarding enabled (/ip ssh set forwarding-enabled=local). See docs/multi-device.md.

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.

SSH connection pooling

By default the server keeps one persistent SSH connection per device and opens a fresh exec channel for each tool call — eliminating the ~200-500 ms handshake overhead that a one-shot connection incurs on every command. Through a jump host the savings double (two handshakes avoided). Idle connections are closed automatically after 30 s.

# Disable pooling (revert to one-shot per tool call)
MIKROTIK_SSH__KEEP_ALIVE=false mikrotik-mcp serve

# Tune the idle timeout (ms)
mikrotik-mcp serve --ssh-idle-timeout 60000

In a JSON config file:

{
  "ssh": {
    "keepAlive": true, // default — set false to disable
    "keepAliveInterval": 10000, // SSH keepalive packet interval (ms)
    "idleTimeout": 30000, // close idle connections after (ms)
  },
}

Connection pooling is SSH-only; MAC-Telnet devices always use one-shot connections. Safe Mode still uses its own dedicated persistent session.

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.

• Security Hardening — granular audit+remediate pairs per risk category (firewall default-deny, address-list enforcement, kernel IP, IPv6 baseline, SSH, service exposure, helpers, management plane, accounts, CRL, segmentation, DNS) plus an orchestrator. Every audit is read-only; every fix defaults to dry-run and snapshots + Safe-Modes before writing, remediating by explicit finding_id.

• Port-Scan Detection — detect (never block) six port-scan signatures (psd, Nmap FIN/NULL/Xmas, SYN/FIN, SYN/RST) by tagging the source, inside a trust-excluding detect-portscan jump-gate; explicit signature selection, trust-list pre-flight, snapshot + Safe-Mode apply.

• 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.