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

uvx mikrotik-mcp

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

In an MCP client's config:

{
  "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:

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.

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:

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:

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

Field	Value
PyPI Project Name	mikrotik-mcp
Owner	StefanKnol
Repository name	mikrotik-mcp
Workflow name	ci.yml
Environment name	pypi

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:

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:

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

uv sync --extra dev
uv run pytest

License

MIT