mikrotik-mcp

An MCP (Model Context Protocol) server for managing fleets of MikroTik RouterOS devices from AI assistants such as Claude.

It exposes 65 tools covering system administration, interfaces, bridging, IP, firewall, DHCP/DNS, PPP, monitoring, and diagnostics — all executed over the RouterOS REST API, with SSH reserved for free-form ros-command execution. Device credentials are never passed through the model: they are resolved from a KeePass vault at runtime.

Highlights

• Fleet-aware by design — every tool accepts a target of a single device ID, a comma-separated list (R1,R2,R3), or all. Commands fan out in parallel and return per-device results; one unreachable device never fails the batch.

• REST-first transport — structured JSON from the RouterOS REST API (RouterOS v7.1+), no brittle terminal scraping. SSH is used only for the ros-command escape hatch.

• KeePass-backed credentials — devices are enumerated from a .kdbx vault group. The LLM only ever sees device IDs, never passwords.

• Safe by default — ros-command defaults to dry-run mode, and a READ_ONLY=true switch withholds all 14 write/execution and active-diagnostic tools, exposing only the 51 state-query tools. Ideal for monitoring-only agent access.

• Two MCP transports — stdio for local clients (Claude Desktop, Claude Code) and Streamable HTTP (with legacy SSE fallback) for a shared team server.

Related MCP server: MikroTik MCP Server

Tool overview

Quick start

1. Prepare the credential vault

Create a KeePass vault (e.g. config/vault.kdbx) with one entry per device inside a group (default: mikrotik):

• Title → device ID (how you'll refer to the device in prompts)

• Username / Password → RouterOS credentials

• URL → device hostname or IP

2. Run with Docker (shared HTTP server)

Using the prebuilt image:

docker run -d -p 8000:8000 \
  -v ./config:/config:ro \
  -e KEEPASS_PASSWORD='…' \
  ghcr.io/vesact/mikrotik-mcp:latest   # serves MCP on http://localhost:8000/mcp

Or build from source:

cp .env.example .env        # set KEEPASS_PASSWORD at minimum
docker compose up -d

3. Or run locally over stdio (Claude Desktop / Claude Code)

npm ci && npm run build

{
  "mcpServers": {
    "mikrotik": {
      "command": "node",
      "args": ["/path/to/mikrotik-mcp/dist/index.js"],
      "env": {
        "KEEPASS_PATH": "/path/to/vault.kdbx",
        "KEEPASS_PASSWORD": "…"
      }
    }
  }
}

Then ask things like:

"What's the RouterOS version across the whole fleet?" "Show DHCP leases on router-01." "Add a firewall filter on R1,R2 — dry-run first."

Configuration

All configuration is via environment variables (see .env.example):

Read-only mode

With READ_ONLY=true (also accepts 1/yes/on), the server exposes only the 51 read-only tools. ros-command, setup-new-device, and all active diagnostics (ping, traceroute, torch, bandwidth test, scans, …) are withheld — they mutate state or generate network traffic. The allow-list is explicit, so tools added in the future are withheld until deliberately classified.

Requirements

• Node.js ≥ 22 (or Docker)

• RouterOS v7.1+ with the REST API enabled (www-ssl or www service) on managed devices

• SSH enabled on devices only if you use ros-command or setup-new-device

Development

npm ci
npm run build          # TypeScript → dist/
npm test               # unit tests (Vitest, no hardware needed)
npm run lint           # ESLint
npm run format         # Prettier
npm run test:integration   # integration tests against real hardware (see .env.test.example)

Unit tests run against fixtures, including a committed test vault (tests/fixtures/test-vault.kdbx, password test-password-123 — fake credentials only). Integration tests require a reachable RouterOS device and are configured via .env.test.

Architecture

MCP client (Claude, …)
   │  stdio / Streamable HTTP
   ▼
mikrotik-mcp server ──► KeePass vault (device inventory + credentials)
   │
   │  fan-out: target = "R1" | "R1,R2" | "all"   (parallel, per-device results)
   ▼
RouterOS REST API (all tools)  /  SSH (ros-command only)

The full architecture document lives in docs/architecture.md, and the original product requirements in docs/prd.md.

Contributing

See CONTRIBUTING.md. Security issues: see SECURITY.md.

License

Licensed under the Apache License 2.0.

Copyright 2026 Actemium Schweiz AG — a VINCI Energies company.

MikroTik and RouterOS are trademarks of Mikrotīkls SIA. This project is not affiliated with or endorsed by MikroTik.