@Ai Solutions.Ru/Mikrotik Server

npm version License: MIT Node.js >=18 MCP SDK 1.16+

High-performance TypeScript MCP (Model Context Protocol) server for MikroTik RouterOS management. Connect Claude, GPT-4, or any MCP-compatible AI to your MikroTik router and manage it through natural language.

npx @ai-solutions.ru/mikrotik-mcp-server

---

🚀 Why This Server?

Feature	This server	jeff-nasseri/mikrotik-mcp	kevinpez (nested fork)
Language	TypeScript / Node.js	Python	Python
Dynamic API Discovery	✅ Browse full RouterOS API tree	❌	❌
Structured JSON output (structuredContent)	✅ Every tool	❌	❌
Zod output schemas	✅ Typed & validated	❌	❌
MCP safety annotations	✅ readOnly/destructive/idempotent	❌	❌
WireGuard VPN management	✅ list + add peers	❌	❌
IPsec peer management	✅	❌	❌
Configuration backup & export	✅ binary + script export	❌	❌
Raw command execution (escape hatch)	✅ execute_command	❌	❌
Pagination on all list tools	✅ limit/offset	partial	partial
Smart output truncation	✅ auto-hint for large results	❌	❌
In-memory caching	✅ discovery cache	❌	❌
MCP SDK version	1.16+ (latest)	old	old
Install via npx	✅ zero config	❌ pip install	❌ pip install

---

✨ Unique Features

1. Dynamic API Discovery (unique in ecosystem)

Browse the entire RouterOS API tree without needing to know command paths in advance. The AI can explore unknown router configurations autonomously.

→ mikrotik_discover_endpoints(path: "/ip")
  Returns: address, arp, dhcp-client, dhcp-server, dns, firewall, hotspot, ipsec, ...

→ mikrotik_get_endpoint_schema(path: "/ip/firewall/filter")
  Returns: available commands (print, add, remove, set, enable, disable) and parameters

This means Claude can discover and interact with any RouterOS subsystem — including packages you've installed, containers, advanced routing, hardware-specific features — without the server needing hardcoded knowledge of them.

2. Structured Content + Zod Output Schemas

Every tool returns both human-readable Markdown and machine-readable JSON via structuredContent. The JSON is validated against Zod schemas, giving you typed, predictable data structures that work with MCP clients that support structured output.

// Example: mikrotik_list_ip_addresses returns
{
  content: [{ type: "text", text: "# IP Addresses\n..." }],   // ← Markdown for AI
  structuredContent: {                                          // ← Typed JSON for clients
    total: 5,
    addresses: [{ id: "*1", address: "192.168.1.1/24", interface: "bridge", ... }]
  }
}

3. MCP Safety Annotations

Tools are annotated with MCP 2025 safety hints so AI clients can present appropriate warnings:

• readOnlyHint: true — safe to call without side effects (list/print operations)
• destructiveHint: true — modifies router state (add/remove/reboot)
• idempotentHint: true — safe to retry
• openWorldHint: true — queries live state from router

The reboot tool additionally requires confirm: true parameter as an extra safety gate.

4. VPN Management (WireGuard + IPsec)

First MikroTik MCP server with WireGuard peer management:

• List all WireGuard peers with traffic stats
• Add new WireGuard peers with endpoint and allowed addresses
• List IPsec peers with profiles
• Graceful handling when WireGuard package isn't installed

5. Raw Command Execution

mikrotik_execute_command provides a full escape hatch to the RouterOS API — execute any RouterOS command with any parameters. This enables AI to handle edge cases, new RouterOS features, or complex operations not covered by specialized tools.

6. Configuration Backup & Export

• mikrotik_create_backup — binary RouterOS backup (survives factory reset)
• mikrotik_export_config — human-readable script export with statistics (line count, command count, size)

---

📋 Full Tool Reference

🖥 System (2 tools)

Tool	Description	Annotations
mikrotik_system_info	CPU, RAM, storage, uptime, version, board info	readOnly
mikrotik_system_reboot	Reboot device (requires confirm: true)	destructive

🔌 Interfaces (3 tools)

Tool	Description
mikrotik_list_interfaces	List all interfaces with type filter + pagination
mikrotik_get_interface	Get detailed info for specific interface
mikrotik_configure_interface	Enable/disable, set MTU, comment

🌐 IP Addresses (3 tools)

Tool	Description
mikrotik_list_ip_addresses	List all IP addresses with interface filter + pagination
mikrotik_add_ip_address	Add IP address to interface
mikrotik_remove_ip_address	Remove IP address by ID

🔥 Firewall (3 tools)

Tool	Description
mikrotik_list_firewall_rules	List filter rules with chain filter + pagination
mikrotik_add_firewall_rule	Add filter rule with full parameter support
mikrotik_remove_firewall_rule	Remove rule by ID

📡 DHCP (3 tools)

Tool	Description
mikrotik_list_dhcp_leases	List leases with status filter + pagination
mikrotik_add_static_lease	Assign static IP to MAC address
mikrotik_list_dhcp_servers	List configured DHCP servers

🔍 DNS (2 tools)

Tool	Description
mikrotik_list_dns_static	List static DNS records with pagination
mikrotik_add_dns_record	Add A/AAAA/CNAME static DNS record

🗺 Routing (3 tools)

Tool	Description
mikrotik_list_routes	List all routes with pagination
mikrotik_add_route	Add static route with distance and routing table
mikrotik_list_nat_rules	List NAT rules with chain filter + pagination

🔐 VPN (3 tools)

Tool	Description
mikrotik_list_wireguard_peers	List WireGuard peers with traffic stats
mikrotik_add_wireguard_peer	Add WireGuard peer with endpoint
mikrotik_list_ipsec_peers	List IPsec peers with profiles

💾 Backup (2 tools)

Tool	Description
mikrotik_create_backup	Create binary system backup
mikrotik_export_config	Export config as text script with statistics

⚡ Execute (1 tool)

Tool	Description
mikrotik_execute_command	Execute any RouterOS API command (destructive)

🔭 Discovery (2 tools)

Tool	Description
mikrotik_discover_endpoints	Browse RouterOS API tree at any path
mikrotik_get_endpoint_schema	Get available commands & params for endpoint

Total: 27 tools + 4 MCP resources

---

📦 MCP Resources

Resource URI	Description
routeros://system/info	Live system info snapshot
routeros://interfaces	All interface states
routeros://firewall/rules	Full firewall ruleset
routeros://routing/routes	All routing table entries

---

🔧 Installation & Setup

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "mikrotik": {
      "command": "npx",
      "args": ["-y", "@ai-solutions.ru/mikrotik-mcp-server"],
      "env": {
        "MIKROTIK_HOST": "192.168.88.1",
        "MIKROTIK_USER": "admin",
        "MIKROTIK_PASSWORD": "yourpassword",
        "MIKROTIK_PORT": "8728",
        "MIKROTIK_SECURE": "false"
      }
    }
  }
}

Environment Variables

Variable	Default	Description
MIKROTIK_HOST	192.168.88.1	Router IP or hostname
MIKROTIK_USER	admin	API username
MIKROTIK_PASSWORD	(required)	API password
MIKROTIK_PORT	8728	RouterOS API port (8729 for TLS)
MIKROTIK_SECURE	false	Use TLS (requires port 8729)
MIKROTIK_TIMEOUT	10000	Connection timeout in ms
DISCOVERY_CACHE_TTL	300	Discovery cache TTL in seconds

Enable RouterOS API

In RouterOS WebFig or terminal:

/ip service enable api

For TLS: /ip service enable api-ssl

---

💬 Example Conversations

"What's the current state of my router?"

Calls mikrotik_system_info → Returns device name, RouterOS version, CPU load, RAM usage, uptime

"Show me all firewall rules that drop traffic"

Calls mikrotik_list_firewall_rules(chain="forward") → Filters by action=drop

"Add a static DNS record for myserver.local pointing to 10.0.0.50"

Calls mikrotik_add_dns_record(name="myserver.local", address="10.0.0.50")

"List all WireGuard peers and their traffic stats"

Calls mikrotik_list_wireguard_peers() → Returns peers with RX/TX bytes

"What API endpoints are available under /container?"

Calls mikrotik_discover_endpoints(path="/container") → Browses RouterOS container API

"Export the full router config as a backup script"

Calls mikrotik_export_config() → Returns full RouterOS export with stats

---

🏗 Architecture

src/
├── index.ts              # Entry point, env config
├── server.ts             # MCP server + tool/resource registration
├── constants.ts          # Configuration constants
├── routeros/
│   └── client.ts         # RouterOS API client (node-routeros)
├── cache/
│   └── memory.ts         # LRU in-memory cache
├── discovery/
│   └── service.ts        # Dynamic API discovery service
├── tools/
│   ├── system.ts         # System info & reboot
│   ├── interfaces.ts     # Interface management
│   ├── ip-address.ts     # IP address CRUD
│   ├── firewall.ts       # Firewall rules
│   ├── dhcp.ts           # DHCP leases & servers
│   ├── dns.ts            # Static DNS records
│   ├── routing.ts        # Routes & NAT
│   ├── vpn.ts            # WireGuard & IPsec
│   ├── backup.ts         # Backup & export
│   ├── execute.ts        # Raw command execution
│   └── discovery.ts      # API discovery tools
├── resources/
│   ├── system-info.ts    # System resource
│   ├── interfaces.ts     # Interfaces resource
│   ├── firewall.ts       # Firewall resource
│   └── routing.ts        # Routing resource
└── utils/
    ├── format.ts         # Formatting, truncation, pagination
    ├── errors.ts         # RouterOS error handling
    └── logger.ts         # Structured logging

---

🔒 Security Notes

• All write operations carry destructiveHint: true annotation
• Reboot requires explicit confirm: true parameter
• Credentials are passed via environment variables (never in code)
• TLS support via MIKROTIK_SECURE=true + port 8729
• Consider using a read-only RouterOS API user for monitoring-only setups

---

📜 License

MIT © AI Solutions