Getting started

This server bridges an MCP client (Claude Desktop, an agent, your own code) and a MikroTik RouterOS device. It connects to the device over SSH and exposes its configuration surface as MCP tools.

PrerequisitesCopy Anchor Link

• Bun ≥ 1.4.4 — the only runtime requirement.
• A reachable RouterOS device with SSH enabled (/ip service → ssh).
• SSH credentials: either a password or an SSH private key for a user with the privileges you intend to manage.

InstallCopy Anchor Link

Global install (recommended)Copy Anchor Link

bun add -g @usex/mikrotik-mcp

This puts a mikrotik-mcp binary on your PATH.

mikrotik-mcp --version      # prints the version, e.g. 1.0.0
mikrotik-mcp --help         # usage and all flags

Run as a shared background serviceCopy Anchor Link

After installing a package that includes the service commands:

mikrotik-mcp-service install

Open http://127.0.0.1:9090 to add routers, then connect your AI clients to http://127.0.0.1:8000/mcp. Update and restart later with mikrotik-mcp-upgrade. The same commands support Windows, macOS and Linux with systemd. See Shared service deployment for the source-checkout setup before publication, startup behavior and troubleshooting.

From sourceCopy Anchor Link

git clone https://github.com/mikrotik-mcp/mikrotik-mcp.git
cd mikrotik-mcp
bun install
bun run start               # runs src/cli.ts serve (stdio transport)

Verify connectivityCopy Anchor Link

Before wiring up a client, confirm the server can actually reach your device. auth-check opens an SSH connection, runs two read-only probe commands (/system identity print and /system resource print), prints the result, and exits.

MIKROTIK_HOST=192.168.88.1 \
MIKROTIK_USERNAME=admin \
MIKROTIK_PASSWORD='your-password' \
mikrotik-mcp auth-check

Equivalent using flags (flags override env vars):

mikrotik-mcp auth-check \
  --host 192.168.88.1 \
  --username admin \
  --password 'your-password'

A successful run prints Connection OK. followed by the device identity and resource output. On failure it prints Connection FAILED. and exits with a non-zero status — check host, credentials, SSH port, and reachability.

See Configuration for every connection option, including key-file authentication.

Create an SSH key from the dashboardCopy Anchor Link

In Devices → Add device / Edit settings → Authentication → SSH key, choose Create key, enter a unique name, then Generate & select key. The MCP host creates an RSA-3072 pair in its user's .ssh directory and selects its private file path in the unsaved device draft. Existing files are never overwritten.

Copy the displayed public key into <name>.pub, upload that file through WinBox → Files, and import it under System → Users → SSH Keys for the intended login user. Only the public key is returned to the browser; never upload the private file. Importing a key can disable password SSH login for that user, so keep an existing management session open until Test connection succeeds. Creating/selecting a key does not install it on the router or save device settings.

Keys are unencrypted for unattended service use, with owner-only file permissions on macOS/Linux. They remain on disk if the device draft is cancelled. In Docker, persist the MCP user's .ssh directory separately from disposable container layers. Native Windows creation is refused until restricted ACLs can be enforced; generate the key with Windows OpenSSH and refresh the existing key picker instead.

First runCopy Anchor Link

Start the server. By default it speaks the stdio transport, which is what Claude Desktop and most local MCP clients expect:

mikrotik-mcp serve          # or just: mikrotik-mcp

All diagnostic logging goes to stderr; stdout is reserved for the JSON-RPC protocol stream. On startup you'll see (on stderr) a line like:

[mikrotik-mcp] INFO MCP server ready on stdio — the enabled tool and prompt counts

Explore the catalogCopy Anchor Link

List every registered tool with its risk level without connecting to a device:

mikrotik-mcp tools

This prints RISK name title rows and a final the current tool and module counts summary. For the full reference with parameters, see the tool reference.

Next stepsCopy Anchor Link

• Connect a client (Claude Desktop, HTTP, custom).
• Choose a transport for local vs. networked deployments.
• Use Safe Mode to make risky changes reversible.