MikroTik RouterOS

io.github.StefanKnolPublished by GitHub account StefanKnolv0.3.1Updated Nov 13, 2026

MikroTik RouterOS over the binary API, addressing rules by real .id not list position.

The publisher's own server: 370.ai — AI Gateway: 100+ Chat Models, Image & Speech Generation

Overview

AI-generated overview

MCP server for administering one MikroTik RouterOS device over the binary API: interfaces, IP, firewall, NAT, DHCP, DNS, routes and logs.

What you can do
  • Read device state: system info, interfaces, IP addresses, routes, DHCP leases, DNS settings and blocklists, logs, connectivity check
  • Inspect firewall filter rules, NAT rules and address lists, including per-rule fields and counters
  • Add, edit, enable/disable, reorder and delete firewall and NAT rules, addressing them by real .id
  • Manage firewall address list entries and static DNS entries, and pin DHCP leases as static
  • Bring interfaces up or down, and read any RouterOS configuration path through a read-only generic listing tool
When to use it
Useful when you want an assistant to inspect or change the configuration of a MikroTik router — auditing firewall and NAT rules, checking what is on the network via DHCP leases, or making targeted rule changes — without driving the CLI over SSH.
Requirements
Runs locally as a Python package via uvx (stdio). Needs network access to the router's API service (api-ssl on port 8729 by default, or 8728 plaintext) and the environment variables MIKROTIK_HOST, MIKROTIK_USERNAME and MIKROTIK_PASSWORD, plus optional MIKROTIK_PORT, MIKROTIK_TLS, MIKROTIK_TLS_FINGERPRINT and MIKROTIK_TIMEOUT. The router user's group must carry the api policy.
Before you install
The server can change and delete live router configuration: removing rules has no undo, and disabling the interface you are connected through cuts the only remote route back. Turning off MIKROTIK_TLS sends the router password in the clear; without MIKROTIK_TLS_FINGERPRINT the self-signed certificate is only encrypted, not authenticated. Use a dedicated non-admin account, since the password is passed by environment variable.

Installation

In SourceWeft

  1. Open MikroTik RouterOS in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

mikrotik-mcp

mcp-name: io.github.StefanKnol/mikrotik-mcp

An MCP server for MikroTik RouterOS, over the binary API rather than by driving the CLI over SSH.

That distinction is the whole point. The CLI prints positional numbers, which are not a rule's identity. A server that lists rules by position and then writes by position either fails outright — where .id=3 matches nothing, so every write reports "not found" for rules that plainly exist — or, worse, succeeds against a different rule once the order has shifted. On a firewall that means deleting the wrong rule.

The binary API returns the real .id (*7, *1f) on every read. So:

  • every read returns id, and every write takes one back;
  • list results also carry position, which is display-only and refused for writes, with an error that explains why;
  • writes read back what they wrote, so a change can be verified rather than assumed;
  • remove_firewall_rule takes an optional confirm_comment and returns the rule it deleted.

Use it

bash
uvx mikrotik-mcp

Configure through the environment — ps would show a password passed as a flag:

VariableDefaultMeaning
MIKROTIK_HOST—Router address. Required.
MIKROTIK_USERNAME—Required.
MIKROTIK_PASSWORD—
MIKROTIK_PORT87298729 for api-ssl, 8728 for plaintext.
MIKROTIK_TLStrue
MIKROTIK_TLS_FINGERPRINT—SHA-256 of the router certificate, to pin it.
MIKROTIK_TIMEOUT10

In an MCP client's config:

json
{  "mcpServers": {    "mikrotik": {      "command": "uvx",      "args": ["mikrotik-mcp"],      "env": {        "MIKROTIK_HOST": "192.168.88.1",        "MIKROTIK_USERNAME": "mcp-agent",        "MIKROTIK_PASSWORD": "..."      }    }  }}

On the router

/ip service enable api-ssl/user group add name=mcp policy=api,read,write,test/user add name=mcp-agent group=mcp password=<strong-password>

The api policy is not optional, and its absence produces a login error identical to a wrong password — so if credentials look right and login still fails, check the group first.

Set MIKROTIK_TLS_FINGERPRINT if you can. MikroTik's API-SSL certificate is self-signed, so ordinary CA validation cannot succeed against a stock device; pinning is what makes the connection authenticated rather than merely encrypted.

Tools

34 of them, covering system info, interfaces, IP addressing, firewall filter (IPv4 and IPv6), firewall address lists, NAT, DHCP leases, DNS, routes and logs — plus ros_list, which reads any RouterOS path and so covers everything without a dedicated tool.

There is deliberately no generic write escape hatch.

Three things worth knowing before the first call:

  • Writes take an id (*7), never a position. Both appear in every list result. position is where a rule currently sits in evaluation order; it shifts whenever anything is added, removed or moved, and it is counted across the whole table rather than within the chain you filtered to. Passing one to a write is rejected rather than guessed at.
  • IPv4 and IPv6 are separate rule sets. The firewall tools take a family and default to ipv4, so a device can read as locked down while its IPv6 table is empty and therefore accepting everything. Listing IPv4 reports the IPv6 rule count for exactly this reason.
  • Address lists hold state no configuration export shows. Entries a rule adds at runtime carry a timeout and exist only in memory. Ask list_address_list_entries for a count_only first: a populated block list can hold tens of thousands.

With mcphub

mcphub puts MCP servers behind one sign-in and grants them out per account. One router is one backend, at its own /mcp/<slug>, registered in a client as its own connector.

Adding it

From the registry — the better default. Add from registry, search for mikrotik-mcp, and the hub builds the settings form from server.json and launches uvx mikrotik-mcp when you enable the backend. It runs in its own process and cannot read credentials the hub holds for anything else. Backends added this way start disabled: open it, look at the tool list, then enable.

As a plugin — install this package into the hub's own environment and mikrotik appears as a backend kind, with typed fields and a Test button that reports the router's identity and RouterOS version. Nicer to configure, but an in-process plugin can read every credential the hub holds. Use it when you build your own hub image.

What to set

Either route asks for the same things. As environment variables:

VariableDefault
MIKROTIK_HOST—Router address. Required.
MIKROTIK_USERNAME—Required. A dedicated user, not admin; its group needs the api policy.
MIKROTIK_PASSWORD—Required.
MIKROTIK_PORT87298729 for api-ssl, 8728 for plaintext.
MIKROTIK_TLStrueTurning it off sends the router password over the network in the clear.
MIKROTIK_TLS_FINGERPRINT—SHA-256 of the router certificate. Pinning it is what makes the TLS connection authenticated rather than merely encrypted.
MIKROTIK_TIMEOUT10Seconds.

No data directory: everything this server reads and writes lives on the router, so there is no local state to keep. Leave Give this server a data directory unticked.

Levels

The hub reads readOnlyHint and destructiveHint from each tool and enforces the grant's level from those alone — a tool above the level is left out of tools/list and refused if called anyway.

LevelGets
viewer17 toolsReads the whole configuration and changes nothing.
user+7 toolsAdds rules and entries, and disables or re-enables them.
admin+10 toolsDeletes, edits in place, and reorders.

viewer — connectivity_check, get_dns_settings, get_firewall_rule, get_logs, get_nat_rule, list_address_list_entries, list_address_lists, list_dhcp_leases, list_dns_adlist, list_dns_static, list_firewall_rules, list_interfaces, list_ip_addresses, list_nat_rules, list_routes, ros_list, system_info.

user adds add_address_list_entry, add_dns_static, add_firewall_rule, add_nat_rule, make_lease_static, set_firewall_rule_enabled, set_nat_rule_enabled. Each of these writes, and none of them takes anything away: adding a rule is a write, not a destruction, and disabling one keeps the rule, its comment and its position so that re-enabling restores exactly what was there. Disabling is the reversible way to find out whether a rule is responsible for something, so it sits here rather than behind admin — the alternative would leave a user with no safe way to test at all.

admin adds the destructive ten:

ToolWhat is lost
remove_firewall_ruleThe rule. The returned copy is the only record.
remove_nat_ruleThe rule.
remove_dns_staticThe entry.
remove_address_list_entryThe entry. A dynamic one returns when its rule next matches; a static one does not.
update_firewall_ruleThe previous values of whatever it sets or clears.
update_nat_ruleThe same.
update_dns_staticThe same.
move_firewall_ruleThe previous order, which is the entire semantics of a firewall.
move_nat_ruleThe same.
set_interface_enabledNothing on disk — but disabling the interface the request came in through severs the only route back, and nothing here can undo that remotely.

A test pins every one of these assignments by name, so a tool added later fails the suite until someone decides which level it belongs to.

Publishing to the MCP registry

server.json is the manifest for the official MCP registry, validated against the published schema. It declares the uvx mikrotik-mcp command and every MIKROTIK_* variable, marking which are required and which are secret — so a client that browses the registry can generate a correct settings form without knowing anything about this server.

Publishing has an order to it, because the registry verifies that whoever publishes an entry actually owns the package it points at.

1. The package must already be on PyPI. The registry fetches pypi.org/pypi/mikrotik-mcp/<version>/json and refuses an entry whose package does not exist. Tag a release and let CI publish it:

bash
git tag v0.1.0 && git push --tags

That needs a PyPI Trusted Publisher first, and because this project does not exist on PyPI yet it has to be a pending publisher — the per-project Publishing tab only appears once a project exists, which is the chicken-and-egg this page solves:

pypi.org → Account settings → Publishing → Add a new pending publisher

FieldValue
PyPI Project Namemikrotik-mcp
OwnerStefanKnol
Repository namemikrotik-mcp
Workflow nameci.yml
Environment namepypi

The environment name matters: the publish job declares environment: pypi, and PyPI rejects the upload if they disagree.

2. The README must carry the ownership token. The registry looks for mcp-name: io.github.StefanKnol/mikrotik-mcp in the PyPI description, which is this file — it is at the top, on its own line. That is what proves the person publishing the registry entry controls the PyPI package.

3. The registry entry publishes itself. The registry job in ci.yml runs after the PyPI upload on the same tag, authenticating with mcp-publisher login github-oidc. GitHub signs a short-lived OIDC token, the registry verifies it and grants the io.github.StefanKnol/* namespace from the repository owner. There is no secret to store and no device-flow login to sit through on each release.

It waits for PyPI to actually serve the new version first. The registry fetches pypi.org/pypi/mikrotik-mcp/<version>/json and refuses an entry whose package it cannot see, and that endpoint lags the upload by some seconds — long enough that publishing straight afterwards races it.

Re-running it is safe: a version already in the registry is the outcome the job exists to produce, so it reports that and passes rather than failing on the registry's duplicate refusal.

To publish by hand — recovering a failed run, or a version released before this job existed:

bash
curl -sL https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz | tar xz mcp-publisher./mcp-publisher login github && ./mcp-publisher publish

login github opens the device flow and proves you are StefanKnol, which authorises the same namespace the OIDC path gets without asking.

The version appears in four places — pyproject.toml, __version__, server.json, and again inside that file's packages entry. Rather than edit them by hand:

bash
uv run python scripts/release.py 0.2.0 --tag

It sets all four, verifies them, commits and tags. The registry treats each version as its own row and checks PyPI has the package at exactly that version, so the nested packages[].version matters as much as the top-level one — and it is the one that gets missed, because the manifest still validates without it. A test enforces that they agree.

Development

bash
uv sync --extra devuv run pytest

License

MIT

Source: README.md at commit 10d61a8

Tools

34

system_info

System Info

Identity, RouterOS version, model, uptime, CPU and memory for the device.

Takes no parameters.

ros_list

Read Any RouterOS Path

Read any RouterOS configuration path. The escape hatch for everything without a dedicated tool. Read-only: it lists items at a path and cannot modify the device.

Parameterspathrequired

list_interfaces

List Interfaces

List every interface with its type, MAC, MTU and running state.

Parameterstype_filterrunning_only

set_interface_enabled

Enable/Disable Interface

Bring an interface up or down. Disabling the interface you are reaching the router through will cut this connection, and nothing here can undo that remotely.

Parametersenabledrequiredinterface_idrequired

list_ip_addresses

List IP Addresses

List configured IPv4 addresses and the interfaces they sit on.

Takes no parameters.

list_firewall_rules

List Firewall Rules

List firewall filter rules in evaluation order. Each rule carries both an `id` and a `position`. Use `id` for any later change: `position` is only where the rule currently sits, and it shifts as soon as anything is added, removed or moved. `position` counts every rule in the table, so a result filtered to one chain is numbered by its place among *all* rules — the first three forward rules might come back as 29, 30, 31. That is the right number for reasoning about evaluation order and the wrong number for anything else.

Parameterschainfamilyverboseinclude_dynamic

get_firewall_rule

Get Firewall Rule

Every field of one firewall rule, including counters.

Parametersfamilyrule_idrequired

add_firewall_rule

Add Firewall Rule

Add a firewall filter rule. Order decides everything in a RouterOS firewall: the first matching rule wins. A new rule appended after a final `drop` is dead code, so set `place_before` unless the end of the chain is genuinely what you want.

Parameterslogpsdportchainrequiredlimitactionrequiredfamilycommentdisableddst_portprotocolsrc_port+21 more

update_firewall_rule

Update Firewall Rule

Change fields on an existing firewall rule. Only the arguments you pass are modified; omitted ones are left alone. To remove a field rather than change it, name it in `unset`. Returns the rule before and after, so the change can be checked rather than taken on trust.

Parameterslogpsdportchainlimitunsetactionfamilycommentrule_idrequireddst_portprotocol+21 more

set_firewall_rule_enabled

Enable/Disable Firewall Rule

Enable or disable one firewall rule, leaving its position intact. Disabling is the reversible way to test whether a rule is responsible for something — prefer it over removing the rule.

Parametersfamilyenabledrequiredrule_idrequired

remove_firewall_rule

Remove Firewall Rule

Delete a firewall rule permanently. There is no undo. Disabling a rule (`set_firewall_rule_enabled`) is almost always the better first move, and the returned copy of the deleted rule is the only record you will have afterwards.

Parametersfamilyrule_idrequiredconfirm_comment

move_firewall_rule

Move Firewall Rule

Reorder a firewall rule relative to another rule. Both ends are given by `id` rather than position, so the move means the same thing even if the list shifted since you last read it. The resulting order is read back and checked against what was asked for. If the rule did not land where it should have, this fails and says so rather than reporting a move that did not happen.

Parametersfamilyrule_idrequiredbefore_rule_id

list_address_lists

List Address Lists

The names of every firewall address list, with entry counts. Start here rather than with `list_address_list_entries`: a firewall built on named lists is unreadable until you know which lists exist, and the dynamic entries that rules create with a timeout never appear in a configuration export. Reads one small row per entry to do the counting, so it is proportional to the total number of entries across all lists.

Parametersfamily

list_address_list_entries

List Address List Entries

List firewall address list entries. `count_only` first, then narrow with `list_name` or `address`. A dynamically populated block list can hold tens of thousands of entries, and asking for all of them is rarely what you want.

Parameterslimitfamilyaddresslist_namecount_onlyinclude_dynamic

add_address_list_entry

Add Address List Entry

Add one entry to a firewall address list. Adding to a list no rule references has no effect; check `list_address_lists` for the name, or search the rules for `src_address_list`.

Parametersfamilyaddressrequiredcommenttimeoutlist_namerequired

remove_address_list_entry

Remove Address List Entry

Remove one entry from a firewall address list. A dynamic entry removed here comes back the moment the rule that created it matches again; change the rule if that is not what you want.

Parametersfamilyentry_idrequiredconfirm_address

list_nat_rules

List NAT Rules

List NAT rules, including port forwards, in evaluation order. NAT is an ordered table with first-match-wins semantics, exactly like the filter chains, so `position` and `id` mean the same things here — `id` for writes, `position` for reading order, counted across both chains rather than within one.

Parameterschainverboseinclude_dynamic

get_nat_rule

Get NAT Rule

Every field of one NAT rule, including counters.

Parametersrule_idrequired

add_nat_rule

Add NAT Rule

Add a NAT rule, such as a port forward. A port forward also needs the forward chain to permit the traffic; check `list_firewall_rules(chain='forward')` for a rule accepting `connection_nat_state='dstnat'` before concluding it is broken.

Parameterslogportchainrequiredactionrequiredcommentdisableddst_portprotocolsrc_portto_portslog_prefixdst_address+12 more

update_nat_rule

Update NAT Rule

Change fields on an existing NAT rule. Only the arguments you pass are modified; omitted ones are left alone. Editing in place keeps the rule's id and its position — removing and re-adding a port forward loses both, and the replacement lands at the end of the table.

Parameterslogportchainunsetactioncommentrule_idrequireddst_portprotocolsrc_portto_portslog_prefix+12 more

move_nat_rule

Move NAT Rule

Reorder a NAT rule relative to another rule. NAT is first-match-wins within a chain, so a broad `masquerade` ahead of a specific `src-nat` means the specific one never runs. Both ends are given by `id`, and the resulting order is read back and checked.

Parametersrule_idrequiredbefore_rule_id

set_nat_rule_enabled

Enable/Disable NAT Rule

Enable or disable one NAT rule, leaving its position intact. Disabling is the reversible way to test whether a port forward is responsible for something — prefer it over removing the rule.

Parametersenabledrequiredrule_idrequired

remove_nat_rule

Remove NAT Rule

Delete a NAT rule permanently. There is no undo, and the returned copy is the only record you will have afterwards. To change a rule rather than replace it, use `update_nat_rule` — it keeps the id and the position.

Parametersrule_idrequiredconfirm_comment

list_dhcp_leases

List DHCP Leases

List DHCP leases — effectively the inventory of what is on the network.

Parameterssearchactive_only

make_lease_static

Make DHCP Lease Static

Pin a dynamic DHCP lease so the device keeps its address.

Parameterscommentlease_idrequired

list_dns_static

List Static DNS

List static DNS entries and regex overrides.

Takes no parameters.

add_dns_static

Add Static DNS Entry

Add a static DNS entry.

Parametersttlnamecnameregexpaddresscommentmatch_subdomain

update_dns_static

Update Static DNS Entry

Change fields on an existing static DNS entry. Only the arguments you pass are modified. Repointing a name at a new address belongs here rather than in remove-then-add: editing keeps the entry's id, so anything holding a reference to it stays valid.

Parametersttlnamecnameregexpaddresscommentdisabledentry_idrequiredmatch_subdomain

remove_dns_static

Remove Static DNS Entry

Delete a static DNS entry.

Parametersentry_idrequired

get_dns_settings

Get DNS Settings

Resolver configuration: upstream servers, cache, and who may query it. `allow-remote-requests` is the field to look at first. With it set, the router answers DNS for anything that can reach port 53, so whether the firewall restricts that reaching is the difference between a LAN resolver and an open one that can be used to amplify traffic at someone else.

Takes no parameters.

list_dns_adlist

List DNS Adlists

Blocklist files the DNS server loads (RouterOS 7.15 and later). Reports a `match-count` per list, which is how you tell a list that is doing work from one that failed to download.

Takes no parameters.

list_routes

List Routes

List the IPv4 routing table.

Parametersactive_only

get_logs

Get Logs

Read the device log, most recent last.

Parameterslimittopicsearch

connectivity_check

Connectivity Check

Confirm the hub can reach and authenticate to this device.

Takes no parameters.

Version history

3
  1. v0.3.1LatestNov 13, 2026
  2. v0.3.0Sep 21, 2026
  3. v0.2.0Sep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Router integrations