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.

• Enforced read-only mode — READ_ONLY=true withholds all 14 write/execution and active-diagnostic tools at the protocol level, exposing only the 51 state-query tools. Ideal for monitoring-only agent access. Approval of individual write calls is left to the MCP client, which is where it can actually be enforced (see Write operations and approval).

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

Configuration

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

When either MCP_ALLOWED_HOSTS or MCP_ALLOWED_ORIGINS is set, the HTTP transports reject requests whose Host/Origin headers are not on the list. Leaving both unset disables the check and the server logs a warning at startup — the HTTP endpoint itself has no authentication, so see SECURITY.md before exposing it.

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.

Write operations and approval

The server does not implement its own confirmation step for writes. Write tools execute on the first call, and ros-command in particular runs whatever it is given, verbatim, on every device matched by target.

Approving individual calls is the MCP client's job — it is the layer that can actually enforce a decision and scope it per agent:

• Claude Code — permission modes plus allow/ask/deny rules, e.g. "deny": ["mcp__mikrotik__ros-command"] or an ask rule for the whole server, in .claude/settings.json.

• Claude Desktop and other hosts — per-tool approval prompts, kept enabled for this server.

ros-command carries MCP annotations (readOnlyHint: false, destructiveHint: true) so clients can classify it without parsing its description.

Two server-side controls remain, because they are enforcement rather than instruction:

• READ_ONLY=true — the tools are never registered, so no client configuration can invoke them.

• The RouterOS credentials in the vault — a device account with restricted permissions bounds what any approved command can do.

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 check          # lint + format check (Biome)
npm run check:fix      # apply Biome's fixes and formatting
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.