@usex/mikrotik-mcp turns MikroTik RouterOS into 901 Model Context Protocol tools any MCP client (Claude Desktop, Claude Code, Cursor, …) can call to read and configure your router by talking to it. It reaches the device over plain SSH — no agent, no package to install on RouterOS — runs on Bun, and validates every call against a schema.

Point it at a router and go:

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

Then just ask:

"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?"

Highlights

• MCP App workspaces — 13 host-themed views, with dedicated investigation, round-trip, service-health, L2 fabric, operations and report workspaces alongside the existing device, interface, firewall and record views. Responsive grids, named path interfaces, expandable evidence and colored JSON keep results readable inside compatible MCP clients. New report views never execute or replay tools. View guide
• Round-trip path lab — model explicit forward/reverse static IPv4 paths across fresh snapshots, with per-hop evidence and declared asymmetry. NAT or unsupported state stops with UNKNOWN; modelled forwarding is not live connectivity. A guided three-step editor selects routers, dated captures and interfaces without writing JSON, with an optional mirrored return path and plain-language result labels. Guide
• Service health contracts — approved DNS/TCP/TLS/HTTPS endpoint checks from the MCP host, optional fresh-export packet regressions, historical evidence, explicit scheduled enrollment and fail-closed rollout gates. Disabled until targets are approved. Guide
• Client/service investigations — save multi-router DHCP/ARP/bridge and network evidence with timestamps, explicit unknowns and next experiments. Router ICMP success never masquerades as verified application health. Guide · Delivery tracker
• Exported client-flow paths — select a recent TCP/UDP flow and visualize its reported ingress/exit, with named VPN-interface lookup and colored JSON evidence. Uses existing NetFlow/IPFIX exports; never enables capture or changes router settings. Missing telemetry remains unknown, not a fabricated blocking hop. Flow-path guide
• 🧰 901 tools, one per RouterOS scope — L2 (bridge, VLAN, wireless, PoE), L3 (addressing, routing, DHCP, DNS), security (firewall, NAT, address-lists, certificates), QoS, and system ops (users, logs, backups, scheduler).
• 🛡️ Attack detection — reads every device's log, correlates brute force, credential spraying and a login that succeeded after failures into incidents with evidence, and can block the source with a timed, reversible entry. Detect-only until you say otherwise. →
• ⏱️ Scheduled audits — run the auditors on a cron with nobody in the loop, and hear only about what changed since the last run: new, worsened, resolved. →
• 📖 explain_device — turns a config into the architecture document that should have been in the wiki (topology diagram, what's exposed, what each chain does), and explains what the difference between two snapshots actually means. →
• 🧪 Offline simulator — trace a hypothetical packet through NAT, routing and firewall against a snapshot, with no device in the loop. Reports UNKNOWN rather than guessing. →
• 📊 Live observability dashboard — a localhost web UI that shows every tool call the AI makes in real time: inputs, outputs, latency, errors, per-device analytics. Secrets redacted. Jump to it ↓
• 🔐 Complete VPN suite — WireGuard, IPsec (IKEv1/IKEv2), L2TP, PPTP, SSTP, OpenVPN, plus GRE/IPIP/EoIP/VXLAN. A choose-vpn-solution prompt picks one for you.
• 🛟 Safe Mode — wrap risky changes in a real transactional window; RouterOS holds them in memory and auto-reverts if your session drops, so you can't lock yourself out.
• 🚦 Risk-annotated — every tool is tagged read / write / destructive, so clients auto-approve reads and prompt on writes.
• 🧱 Injection-safe — a command builder quotes/escapes every value; a hostname like LAN; /system reset can never split into a second command.
• 🖧 Multiple devices — name your routers and target one per call; configure both ends of a tunnel in one conversation.
• 🪜 SSH jump hosts — reach a router with no exposed port by tunnelling through a bastion (jumpVia); commands, Safe Mode and file upload all ride the hop.
• ⚡ Connection pooling — one persistent SSH session per device saves ~200-500 ms per command.
• 🔀 REST API, opt-in — point a device at RouterOS 7.9+'s /rest for structured JSON and real HTTP status codes, with automatic SSH fallback for anything REST can't express. Per-device, off by default.

Install

# Requires Bun ≥ 1.3 — https://bun.sh
bun add -g @usex/mikrotik-mcp

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

# Wire it into your MCP client (stdio by default)
mikrotik-mcp serve

Prefer SSH keys? Swap the password for a key file (add a passphrase if it's 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"

Prefer a one-click bundle (no Bun/Node/npm on the machine, credentials entered in the host UI)? Build an .mcpb and drag it into Claude Desktop → Settings → Extensions:

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

Full options: docs/configuration.md · MCPB details: docs/getting-started.md.

Simple usage — by scenario

Once the server is wired into your client, everything below is a plain-language request. The AI picks the right tool, validates it, and runs it. No CLI syntax to memorize.

🔎 See what's on the router

"List the firewall filter rules and flag anything that allows WAN → LAN." "What DHCP leases are active right now?" "Show interface traffic and tell me which port is saturated."

All read-only — safe to auto-approve.

🧱 Make a change, safely

"Enable safe mode, block inbound SSH on the WAN, then commit if I'm still connected."

Safe Mode holds the change in memory and reverts automatically if you lock yourself out:

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

🔐 Stand up a VPN

"Create a WireGuard interface on port 13231 and generate a client config for my laptop." "Build an IKEv2 site-to-site tunnel to 203.0.113.5 for 192.168.20.0/24."

Not sure which VPN? Ask the choose-vpn-solution prompt — it recommends one and outlines the build. Every technology is covered:

| Need | Use | Build it with | | ----------------------------------- | ----------------------- | -------------------------------------------------------------------------------------- | | MikroTik ↔ MikroTik, modern clients | WireGuard | create_wireguard_interface, add_wireguard_peer, generate_wireguard_client_config | | Interop site-to-site / native IKEv2 | IPsec | create_ipsec_{profile,peer,identity,proposal,policy}, get_ipsec_active_peers | | Built-in OS VPN clients | L2TP/IPsec | set_l2tp_server, create_ppp_secret, create_ppp_profile | | Through restrictive firewalls | SSTP (TLS) | set_sstp_server, create_sstp_client | | Cross-platform | OpenVPN | set_ovpn_server, create_ovpn_client | | Route / L2-bridge between sites | GRE/IPIP/EoIP/VXLAN | create_gre_tunnel, create_eoip_tunnel, create_vxlan_tunnel |

Details: docs/vpn-guide.md.

🖧 Manage several routers at once

Name your routers and drive them all from one conversation — exactly what you need to set up a tunnel between two MikroTiks and test it from both ends:

// 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

Every tool gains an optional device argument, and Safe Mode is per-device:

"On site-a create a WireGuard interface, on site-b add it as a peer, then ping across."

Behind a bastion with no exposed port? Jump through another router (jumpVia) — commands, Safe Mode and SFTP all ride the hop. Full guide: docs/multi-device.md.

🩺 Diagnose and harden

"Why can't VLAN 50 reach the internet?" "Audit my firewall for shadowed and overly-broad rules." "Harden this router and show me the exact diff before committing."

These map to higher-level workflows — firewall audit, security hardening, change plan & dry-run — each read-only to inspect, dry-run + Safe Mode to fix.

📊 Observability dashboard

A localhost web dashboard that watches every tool call the LLM makes against this server — in real time. Off by default, zero overhead until you flip it on, and it runs alongside whatever transport you use:

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

Every call flows through one choke point in the registry, so the dashboard sees all of them, across every transport. Why you'll want it on:

• 👁️ Live feed of every call — tool, inputs, outputs, target device, duration, success/error — streaming in over a Bun-native WebSocket (SSE fallback). Filter by tool / risk / device / status / free-text, pause & resume, export to CSV or JSON.
• 📈 Analytics at a glance — calls in window, calls/min, error rate, avg / p95 / p99 latency, distinct tools, output volume; top tools, by-risk and status donuts, by-device bars, and a recent-errors panel.
• 🔒 Secrets redacted before storage — any password, private key, PSK or token is replaced with «redacted» before anything is stored or streamed. Set --dashboard-capture-body=false to keep metadata only.
• 🕸️ Devices & connectivity map — a hub-and-spoke graph of the server to each device, coloured by live SSH reachability, with per-device online/offline, latency, RouterOS identity/version and recent activity.

It also carries a page per flagship workflow — Attacks (live incidents, the evidence behind each, guarded blocking), Schedules (audit posture over time and what regressed), Explain (the architecture document with its topology diagram), Policies, Simulator, Transactions, Flows and Rollout — plus Config Studio (edit the config JSON with autocomplete + safe-apply auto-rollback), a live topology map from MNDP discovery, a releases/upgrade timeline, and a reload/restart button. Everything persists to a Bun-native SQLite store on your machine — no external database. Binds to loopback (127.0.0.1) by default; set a bearer token (--dashboard-token) to expose it safely.

Live feed — call detail drawer. One call expanded: arguments, output, target device, duration, risk annotation — secrets already «redacted».

Clients. Every DHCP lease / connected station across devices, with identity, traffic and last-seen.

RADIUS & User Manager. Servers, sessions, profiles, limitations and vouchers.

Topology. Live L2 map built from MNDP neighbour discovery.

Packets. Packet captures started from the dashboard, with status and download.

Snapshots. /export-based config snapshots kept locally — browse and diff any two.

Drift Guard. Baseline vs. live config, with drift promoted or reconciled.

Change Plan. Dry-run a batch of changes, review the exact commands, then apply under Safe Mode.

S3 Backups. Off-device backup archive — upload, list, download, delete.

Backups. Local backup files kept on the MCP host.

Modules. The full tool catalog by module and risk annotation.

Config. Config Studio — edit the config JSON with autocomplete, then safe-apply with auto-rollback.

Memory. Knowledge graph of entities, relations and observations gathered from calls.

What's new. Release notes for the running server version, shown on first launch after an upgrade.

Full reference: docs/observability.md.

The dashboard includes a responsive operations shell with searchable grouped navigation, pinned page shortcuts, a mobile drawer, and coordinated light/dark themes. The activity chart pairs a dotted canvas with animated successful-call trends and independent error bars, with reduced-motion and pause controls. BeUI now powers the dashboard's shared buttons, inputs, badges, checkboxes, switches, selects, tabs, tooltips, loaders, theme toggle and animated numbers. Animated Sidebar adds a collapsible icon rail while retaining search and pins. Live Feed uses Animated Badges and an Expandable Action Bar; Overview, Devices and Live Feed offer read-only Pull to Refresh with a keyboard-accessible button. The local BeUI registry retains the 17 collections used by the dashboard and their supporting components; unused component demonstrations have been removed. The fixed Operations Island expands into live activity, router checks and recent tool completions, using existing data without extra probes or configuration changes. Missing and stale observations are explicitly labelled. For frontend development, bun run dev:dashboard connects the UI on port 9191 to the existing dashboard backend on port 9091. See the dashboard design system.

Access Scope settings can be edited directly in the dashboard: configure risk ceilings, router allow/block lists and tool-name patterns, preview permission decisions without executing tools, then review and apply with a 60-second auto-revert window. The page distinguishes the operator policy, runtime session restrictions and server read-only mode. See Access Scope settings.

The tool catalog

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

| Group | Tools | Modules | | ------------------------ | ----: | ------------------------------------------------------------------------------------------------------------------------------ | | System & Ops | 194 | system, network tools, investigations, service contracts, round-trip paths, Safe Mode, transactions, rollout, scheduled audits | | Security | 127 | firewall filter, NAT, address-lists, certificates, IP services, hardening, policy-as-code, attack detection | | VPN & Tunneling | 108 | WireGuard, IPsec, PPP, L2TP, PPTP, SSTP, OpenVPN, GRE/IPIP/EoIP/VXLAN | | Dynamic Routing | 99 | router-id, tables, rules, next-hops, filters, BFD, BGP, OSPF, RIP, PIM-SM, IGMP proxy, GMP, RPKI | | IPv6 | 90 | addressing, DHCPv6, ND, neighbours, pools, routes, firewall filter/NAT/mangle/raw | | Tools | 67 | ping, traceroute, bandwidth test, sniffer, traffic generator, RoMON, Wake-on-LAN, SMS | | Addressing & Routing | 62 | IP addresses, IP pools, routing, DHCP, DNS | | Interfaces | 56 | interfaces, VLAN, bridge, wireless, PoE | | AAA | 34 | RADIUS, User Manager, 802.1X | | QoS | 23 | queue types, queue trees, simple queues | | Switch | 18 | switch settings, ports, rules, port isolation | | Discovery & Meta | 11 | tool gateway (find/describe/invoke), server pulse, capability probe | | Memory | 9 | persistent knowledge graph |

Beyond the catalog

Higher-level workflows built on top of the per-scope tools:

• Change Plan & Dry-Run — preview commands as a terraform-style plan, apply under Safe Mode, show the exact /export diff, commit only if still reachable.
• Cross-Device Transactions — coordinate Safe Mode across several routers: the recommended MCP workflow for related VPN, peering, route and ACL changes. Plan → stage → verify → commit with approval. Best-effort, not ACID; partial commits require manual recovery. Connection instructions and cross-device prompts steer the model here before independent writes, not for read-only tasks.
• Staged Fleet Rollout — apply one change as canary → wave → fleet with a health gate and soak between waves, reverting everything already changed on the first failure.
• Scheduled Audits — run the auditors on a cron with nobody in the loop and alert only on what changed since the previous run: new, worsened, resolved.
• Config Narrative — turn a router's configuration into a plain-language architecture document with a topology diagram, and explain what the difference between two snapshots actually means.
• Attack Detection — watch the fleet's logs for brute force, credential spraying and a login that succeeded after failures, correlate them into incidents with evidence, and block the source reversibly when you ask.
• Config Snapshots — store /export snapshots and time-travel diff any two, or one against the live device.
• Firewall Audit — find shadowed, broad, missing-default-drop, duplicate and dead rules, risk-scored, with one-click fixes.
• Security Hardening — per-category audit+remediate pairs; audits read-only, fixes dry-run + snapshot + Safe-Mode first.
• Policy-as-Code — write your own compliance rules in YAML and lint a config snapshot offline; Markdown/JSON/SARIF, read-only, CI-able.
• Offline Simulator — trace a hypothetical packet through NAT, routing and firewall against a snapshot; reports UNKNOWN rather than guessing.
• Traffic Flow — NetFlow/IPFIX collection and continuous top-talker / conversation / application analytics; flow metadata only, no payload.
• Port-Scan Detection · Packet Capture Studio · Discovery · Config Studio.

Built-in prompts

MCP prompts are one-click guided workflows — 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

| Transport | When | Run | | ------------------- | --------------------------------- | ---------------------------------------------------------------- | | stdio (default) | Claude Desktop, local MCP clients | mikrotik-mcp serve | | streamable-http | Remote / shared, behind a proxy | mikrotik-mcp serve --transport streamable-http --mcp-port 8000 | | sse | Legacy HTTP clients | mikrotik-mcp serve --transport sse |

HTTP transports expose POST /mcp and GET /health with DNS-rebinding protection. See docs/transports.md.

Configuration

Settings come from MIKROTIK_* env vars or matching CLI flags (defaults → env → flags):

| Variable | Flag | Default | Purpose | | ----------------------------- | ------------------ | ----------- | ----------------------------------- | | MIKROTIK_HOST | --host | 127.0.0.1 | RouterOS host | | MIKROTIK_USERNAME | --username | admin | SSH user | | MIKROTIK_PASSWORD | --password | — | SSH password (or use a key →) | | MIKROTIK_KEY_FILENAME | --key-filename | — | SSH private-key file path | | MIKROTIK_KEY_PASSPHRASE | --key-passphrase | — | Passphrase for an encrypted key | | MIKROTIK_JUMP_HOST | --jump-host | — | SSH bastion to tunnel through | | MIKROTIK_CONFIG_FILE | --config | — | JSON file of named devices | | MIKROTIK_DEVICES | --devices | — | Inline JSON of named devices | | MIKROTIK_MCP__TRANSPORT | --transport | stdio | stdio / streamable-http / sse | | MIKROTIK_SSH__KEEP_ALIVE | --ssh-keep-alive | true | SSH connection pooling | | MIKROTIK_DASHBOARD__ENABLED | --dashboard | false | Real-time observability dashboard |

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

Documentation

| Doc | | | ------------------------------------------------------------------- | ------------------------------------------------------------ | | Getting started | Install, verify, first run | | Configuration | Every env var & flag | | Device capabilities | What a router supports; how tools are gated on it | | Alerting | Rules that reach out — Slack, Discord, ntfy, webhook, MCP | | Multiple devices | Manage several routers; per-call targeting | | Connecting clients | Claude Desktop, stdio, HTTP | | Observability | Real-time dashboard: live feed + analytics, SQLite | | Safe Mode | Transactional changes | | Cross-Device Transactions | Two-phase commit across several routers | | Staged Fleet Rollout | Canary → wave → fleet with health gates and auto-revert | | Change Plan & Dry-Run | Preview commands, apply with the exact diff + auto-rollback | | Traffic Flow | NetFlow/IPFIX collection + top-talker analytics | | Attack Detection | Live attack incidents from logs; guarded, timed blocking | | Firewall Audit | Shadowed/broad/dead rules, risk-scored | | Security Hardening | Per-category audit+remediate, snapshot + Safe-Mode | | Scheduled Audits | Auditors on a cron, alerting only on run-over-run changes | | Policy-as-Code | Your own YAML compliance rules, linted offline → SARIF | | Config Narrative | Config → architecture doc + Mermaid; consequence-level diffs | | Offline Simulator | Trace a packet through firewall + routing, no device | | VPN guide | Every tunnel type + how to build it | | Prompts | The 9 guided workflows | | Architecture · Security | How it's built · credentials & risk gating | | Tool reference | The full generated catalog | | Development · Docker | Build, test, deploy |

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 tools are annotated so clients can require confirmation. Details: docs/security.md. Only point this at devices you're authorized to manage.

License

MIT. Reuse freely. No warranty.