MCP 服务器

mikrotik-mcp

Turns a MikroTik router into 310 MCP tools for AI-driven configuration over SSH, covering firewall, routing, VPN, and more.

README

<div align="center"> <img src="assets/logo.svg" alt="@usex/mikrotik-mcp" width="440" /> <p><strong>A Bun-native MCP server that turns one or more MikroTik routers into 466 tools your AI can drive.</strong><br/> Firewall · routing · DHCP/DNS · wireless · QoS · and a complete VPN suite — over SSH, with transactional Safe Mode.</p>

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

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

Group	Tools	Modules
Interfaces	41	interfaces, VLAN, bridge, wireless, PoE
Addressing & Routing	46	IP addresses, IP pools, routing, DHCP, DNS
Dynamic Routing	99	router-id, settings, tables, rules, next-hops, filters, BFD, BGP, OSPF, RIP, PIM-SM, IGMP proxy, GMP, RPKI
Security	34	firewall filter, NAT, address-lists, certificates, IP services
VPN & Tunneling	96	WireGuard, IPsec, PPP, L2TP, PPTP, SSTP, OpenVPN, GRE/IPIP/EoIP/VXLAN
QoS	19	queue types, queue trees, simple queues
System & Ops	102	system, network tools, scheduler/scripts, users, logs, backup, Safe Mode

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):

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

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

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

Variable	Flag	Default	Purpose
`MIKROTIK_HOST`	`--host`	`127.0.0.1`	RouterOS host
`MIKROTIK_USERNAME`	`--username`	`admin`	SSH user
`MIKROTIK_PORT`	`--port`	`22`	SSH port
`MIKROTIK_PASSWORD`	`--password`	—	SSH password (or use a key →)
`MIKROTIK_KEY_FILENAME`	`--key-filename`	—	SSH private-key file path
`MIKROTIK_PRIVATE_KEY`	`--private-key`	—	Inline private key (PEM)
`MIKROTIK_KEY_PASSPHRASE`	`--key-passphrase`	—	Passphrase for an encrypted key
`MIKROTIK_CONFIG_FILE`	`--config`	—	JSON file of named devices (multi-device)
`MIKROTIK_DEVICES`	`--devices`	—	Inline JSON of named devices
`MIKROTIK_MCP__TRANSPORT`	`--transport`	`stdio`	`stdio` / `streamable-http` / `sse`
`MIKROTIK_MCP__PORT`	`--mcp-port`	`8000`	HTTP bind port

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 466 tools with risk, description, and input schema
schemas/tools/<name>.json — per-tool input schema
schemas/config.schema.json — the runtime configuration

Documentation

Doc
Getting started	Install, verify, first run
Configuration	Every env var & flag
Multiple devices	Manage several routers; per-call targeting
Connecting clients	Claude Desktop, stdio, HTTP
Transports	stdio / HTTP / SSE, DNS-rebinding
Safe Mode	Transactional changes
VPN guide	Every tunnel type + how to build it
Prompts	The 9 guided workflows
Architecture	How it's built
Security	Credentials, risk gating
Tool reference	All 466 tools
MCP Inspector	Test tools/prompts in the UI or CLI
Development · Docker	Build, test, deploy

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.

<div align="center"> <img src="assets/logo-icon.svg" width="56" alt="" /><br/> Made with ❤️ by <a href="https://github.com/ali-master">Ali Torki</a> </div>