MikroMCP

<img alt="MikroMCP" src="https://github.com/AliKarami/MikroMCP/raw/v1.6.0/docs/assets/MikroMCP-logo-dark.png" width="700">

AI-native network automation for MikroTik RouterOS. MikroMCP exposes RouterOS as a typed, auditable Model Context Protocol server so Claude, Cursor, Codex, and other MCP clients can inspect, diagnose, and safely operate MikroTik routers in natural language.

MikroMCP exists because raw router CLI access is the wrong abstraction for AI agents. RouterOS is powerful, but asking an LLM to improvise shell commands against production network gear is risky. MikroMCP gives agents a controlled tool surface: strict schemas, idempotent writes, dry-run previews, per-router circuit breakers, retry policies, RBAC, audit logs, snapshots, and rollback-aware change workflows.

In one sentence: MikroMCP turns MikroTik RouterOS into a production-minded MCP control plane for AI infrastructure, DevOps automation, and modern router management.

---

Why It Matters

Instead of...	MikroMCP gives you...
Hand-written RouterOS CLI snippets from chat	Typed MCP tools with strict Zod validation
Blind config changes	Dry-run previews, idempotency checks, snapshots, and rollback tooling
One-off scripts per router	A multi-router registry with per-router credentials, tags, TLS, SSH, and maintenance windows
Raw network access for every assistant	RBAC identities, bearer tokens for HTTP mode, tool allowlists, and audit trails
Fragile troubleshooting workflows	Router-originated ping, traceroute, torch, logs, interfaces, DHCP, firewall, routes, WiFi, WireGuard, and more

---

Feature Showcase

Category	What MikroMCP covers
🧭 Router management	System status, clock, reboot, packages, files, scripts, scheduler jobs, containers
🌐 Network operations	Interfaces, VLANs, IP addresses, DHCP leases, DNS static records, bridge ports, WiFi clients
🔥 Firewall and policy	Filter/NAT rules, mangle rules, address lists, route tables, routing rules
🛰️ Routing visibility	Static routes, routing tables, BGP peers, OSPF neighbors
🔐 Secure access	HTTP bearer auth, bcrypt token hashes, RBAC, router/tool restrictions, confirmation tokens
🧪 Diagnostics	Router-originated ping, traceroute, torch, log filtering, guarded SSH command execution
🛡️ Change safety	Dry-run, idempotent writes, snapshots, write journal, plan_changes, apply_plan, rollback_change
⚙️ Production behavior	Retries for read tools, per-router circuit breakers, correlation IDs, structured logs, audit logs
🤖 AI-agent fit	Human-readable responses plus structured JSON content for reasoning, chaining, and automation; server advertises an instructions string on MCP initialize so clients self-configure; optional routerId resolved via MIKROMCP_DEFAULT_ROUTER for single-router setups; usage skill for safe, guided tool use in Claude Code
🧩 MCP compatibility	stdio for desktop clients, Streamable HTTP and legacy SSE for remote or service-style clients

---

Demo

Usage

Review by Claude

MCP Inspector

---

Quick Start

Prerequisites

• Node.js 22 or newer (for npm install) — or use a standalone binary below
• MikroTik RouterOS 7.x with the REST API enabled
• A RouterOS user with the policies your tools require

Recommended RouterOS policies for full tool coverage:

read, write, api, rest-api, test, ssh, sniff, ftp

ssh is required for ping, traceroute, torch, and run_command. sniff is required by torch. ftp is required only for upload_file.

---

Install

npm (recommended)

npm install -g mikromcp

Standalone binaries

Download the binary for your platform from the latest GitHub release — no Node.js required.

Docker

docker pull ghcr.io/alikarami/mikromcp:latest

---

Set Up With the Init Wizard

Run the interactive setup wizard:

mikromcp init

The wizard will ask for your router details and write everything to ~/.mikromcp/:

~/.mikromcp/
├── routers.yaml      # router registry
├── identities.yaml   # RBAC identities (HTTP mode)
└── .env              # credentials and runtime settings

~/.mikromcp/.env is loaded automatically every time MikroMCP starts — no shell exports or Claude Desktop env blocks needed. Fill in the credentials it generates:

# ~/.mikromcp/.env  (generated by mikromcp init)
ROUTER_CORE01_USER=
ROUTER_CORE01_PASS=

To edit your router registry directly:

nano ~/.mikromcp/routers.yaml

routers:
  core-01:
    host: "192.168.88.1"
    port: 443
    tls:
      enabled: true
      rejectUnauthorized: true
    credentials:
      source: "env"
      envPrefix: "ROUTER_CORE01"
    tags: ["core"]
    rosVersion: "7"

---

Verify With Doctor

mikromcp doctor

Doctor checks Node version, config files, router reachability, Claude Desktop registration, and whether a newer version is available.

---

Run

stdio (for Claude Desktop and other desktop MCP clients)

mikromcp serve

HTTP mode (for service deployments)

MIKROMCP_TRANSPORT=http mikromcp serve

---

Connect An MCP Client

Claude Desktop

Run mikromcp init and choose Register with Claude Desktop — it patches claude_desktop_config.json automatically.

Or add it manually to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS:

{
  "mcpServers": {
    "mikromcp": {
      "command": "mikromcp",
      "args": ["serve"]
    }
  }
}

No env block needed — credentials are loaded from ~/.mikromcp/.env at startup. Restart Claude Desktop, then ask:

Use MikroMCP to show CPU, memory, uptime, active interfaces, and warning logs for core-01.

HTTP / SSE Mode

HTTP mode is useful for service deployments and MCP clients that connect over a network endpoint.

Set in ~/.mikromcp/.env:

MIKROMCP_TRANSPORT=http
MIKROMCP_PORT=3000
MIKROMCP_CONFIRMATION_SECRET=<openssl rand -hex 32>

Then run:

mikromcp serve

Every HTTP request must include:

Authorization: Bearer <token>

Tokens are configured as bcrypt hashes in ~/.mikromcp/identities.yaml. Use mikromcp init to generate them.

Docker

docker run --rm \
  -e MIKROMCP_TRANSPORT=http \
  -e MIKROMCP_PORT=3000 \
  -e MIKROMCP_CONFIRMATION_SECRET="$(openssl rand -hex 32)" \
  -e ROUTER_CORE01_USER=mcp-api \
  -e ROUTER_CORE01_PASS=your-router-password \
  -e MIKROMCP_CONFIG_PATH=/config/routers.yaml \
  -v "$HOME/.mikromcp:/config:ro" \
  -p 3000:3000 \
  ghcr.io/alikarami/mikromcp:latest

Pass MIKROMCP_CONFIG_PATH and MIKROMCP_IDENTITIES_PATH explicitly when running in Docker since ~/.mikromcp/ inside the container refers to the container's home directory.

---

Configuration Reference

All settings can be placed in ~/.mikromcp/.env or passed as environment variables. Values in ~/.mikromcp/.env are loaded at startup; explicit environment variables always take precedence.

Variable	Default	Purpose
MIKROMCP_TRANSPORT	stdio	stdio or http
MIKROMCP_CONFIG_PATH	~/.mikromcp/routers.yaml	Router registry path
MIKROMCP_DEFAULT_ROUTER	unset	Router ID used when a tool call omits routerId; falls back to the sole configured router if only one exists
MIKROMCP_IDENTITIES_PATH	~/.mikromcp/identities.yaml	Identity and bearer-token registry
MIKROMCP_STDIO_IDENTITY	built-in superadmin	Named identity for stdio mode
MIKROMCP_PORT	3000	HTTP transport port
MIKROMCP_BIND_HOST	127.0.0.1	HTTP bind address
MIKROMCP_CONFIRMATION_SECRET	unset	HMAC secret for destructive-action confirmation tokens
MIKROMCP_AUDIT_LOG_PATH	unset	Optional NDJSON audit log file path
MIKROMCP_DATA_DIR	~/.mikromcp/data	Snapshots and write-journal directory
MIKROMCP_HTTP_MAX_BODY_BYTES	1048576	HTTP request body cap
MIKROMCP_HTTP_RATE_LIMIT_RPM	60	Requests per minute per IP; 0 disables rate limiting
MIKROMCP_SSH_COMMAND_TIMEOUT_MS	30000	SSH command timeout
MIKROMCP_SSH_MAX_OUTPUT_BYTES	524288	SSH output cap
MIKROMCP_CMD_ALLOW	unset	Global allowlist patterns for run_command
MIKROMCP_CMD_DENY	unset	Global denylist patterns for run_command
ROUTER_<PREFIX>_USER	unset	Router username from envPrefix
ROUTER_<PREFIX>_PASS	unset	Router password from envPrefix

---

Available Tools

MikroMCP currently registers 117 MCP tools.

Area	Tools
System	get_system_status, get_system_clock, set_system_clock, reboot
Interfaces and IP	list_interfaces, manage_vlan, manage_ip_address
DHCP and DNS	list_dhcp_leases, manage_dhcp_lease, list_dns_entries, manage_dns_entry, get_dns_settings, manage_dns_settings
DHCP Servers & Pools	list_dhcp_servers, manage_dhcp_server, list_ip_pools, manage_ip_pool
DHCP Clients	list_dhcp_clients, manage_dhcp_client