repository·master·Indexed 42 days ago
https://github.com/jeff-nasseri/mikrotik-mcpAn MCP server that enables AI assistants like Claude to manage MikroTik RouterOS devices using natural language. It provides a bridge for executing network configuration and management tasks, including VLAN operations, DHCP setup, firewall rules, and wireless configuration. It features a multi-device inventory system for fleet management, allowing for tagged rollouts, configuration comparisons, and fleet-wide updates via an LLM.
MikroTik MCP acts as a bridge between AI assistants (like Claude Desktop) and MikroTik RouterOS devices. It enables LLMs to interact with your network infrastructure using natural language. Through this interface, an AI assistant can perform tasks such as:
The MikroTik MCP server provides a wide range of tools categorized by their functional area on a MikroTik device. You can use these tools to manage everything from basic device inventory to advanced networking configurations like WireGuard, VLANs, and Firewall rules.
Available tool categories include:
When an inventory is configured, the MCP server manages multiple devices. Every tool accepts a device argument corresponding to the inventory title.
Key Concepts:
list_devices tool to find available device titles, hosts, tags, and regions.title (e.g., office-core), by tags (e.g., tag: office), or by region.Every command opens its own SSH connection to the target device and closes it immediately upon completion. Connections are not pooled or shared. This ensures that multiple client sessions talking to the same server process do not interfere with each other (no 'shared fate'), though it does incur the cost of one SSH handshake per command.
Safe mode is managed on a per-device basis. Enabling safe mode on one device does not affect any other device in your inventory. Each device maintains its own persistent safe mode session.
The MCP server provides specific capabilities to allow an LLM to manage multiple devices seamlessly:
list_devices tool allows the LLM to see all managed devices, including their title, host, tags, and region. Credentials are never exposed.interfaces, firewall, vlan) accepts an optional device parameter. The LLM uses the title from the inventory to specify which router to act upon.device parameter or provides an incorrect title, the server returns an error listing all valid device titles. This allows the LLM to self-correct.When managing multiple devices, every device-scoped tool accepts an optional device argument.
device argument.title of the target device.Omitting the device argument when multiple devices exist will result in an error listing the available device titles.
list_devices() # discover the fleet
list_interfaces(device="TitleA") # target one device
create_vlan_interface(device="TitleB", name="vlan100", vlan_id=100, interface="ether1")The MikroTik MCP uses a multi-device inventory architecture to manage a fleet of routers. The workflow is as follows:
title to the connector.title to the corresponding device's SSH client.To discover the available fleet, the LLM uses the list_devices tool.
MikroTik Safe Mode protects against misconfigurations by holding all changes in memory only. In the context of this MCP server, Safe Mode works by opening a persistent SSH shell and sending a Ctrl+X command to the router.
Key behaviors:
commit_safe_mode to write changes to permanent storage (flash/NVRAM) or rollback_safe_mode to discard them.1. **Enable** — opens a persistent SSH shell and sends Ctrl+X to the router
2. **Make changes** — every subsequent tool call is routed through the same session
3. **Commit or Rollback** — send a second Ctrl+X to persist, or close the session to revert0.14.0, MikroTik MCP supports managing multiple MikroTik devices organized within a fleet structure. This allows an LLM to interact with an entire inventory of devices rather than being limited to a single connection, enabling fleet-wide management and querying.Instead of configuring a single device via environment variables, you can provide a YAML inventory file. This allows the MCP server to manage a fleet of MikroTik devices.
Important Notes:
MIKROTIK_INVENTORY_FILE (the image uses /config as the mount point).uid 1000 (mcpuser), so ensure the mounted file is readable (e.g., chmod 644 inventory.yaml).MIKROTIK_HOST, etc.) are ignored.Example inventory.yaml structure:
- title: TitleA
host: 192.168.88.1
port: 22
username: admin
password: change-me
region: NL
tags: [branch]
- title: TitleB
host: 192.168.89.1
port: 22
username: admin
key_filename: /config/keys/id_ed25519Running with Docker CLI:
docker run --rm -i \
-v "$PWD/inventory.yaml:/config/inventory.yaml:ro" \
-e MIKROTIK_INVENTORY_FILE=/config/inventory.yaml \
ghcr.io/jeff-nasseri/mikrotik-mcp:latestIntegration tests should use testcontainers to spin up a real MikroTik RouterOS container.
Guidelines:
@pytest.mark.integration decorator.To run your integration tests, use:
pytest tests/integration/test_my_feature_integration.py -v
"""Integration tests for MikroTik my feature using testcontainers."""
import pytest
from mcp_mikrotik.scope.my_feature import (
mikrotik_create_my_resource,
mikrotik_list_my_resources
)
@pytest.mark.integration
class TestMikroTikMyFeatureIntegration:
def test_01_create_resource(self, mikrotik_container):
result = mikrotik_create_my_resource(
name="test_resource",
required_param="test_value"
)
assert "failed" not in result.lower()
assert "test_resource" in result
def test_02_list_resources(self, mikrotik_container):
result = mikrotik_list_my_resources()
assert "test_resource" in result