MikroTik RouterOS

io.github.StefanKnol由 GitHub 账号 StefanKnol 发布v0.3.1更新于 Nov 13, 2026

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

发布方自己的服务:370.ai — AI Gateway: 100+ Chat Models, Image & Speech Generation

概览

AI 生成的概览

通过二进制 API 管理单台 MikroTik RouterOS 设备的 MCP 服务器,可查看和修改接口、IP、防火墙、NAT、DHCP、DNS、路由与日志。

可以做什么
  • 读取设备状态:系统信息、接口、IP 地址、路由、DHCP 租约、DNS 设置与拦截列表、日志,以及连通性检查
  • 查看防火墙过滤规则、NAT 规则和地址列表,包括单条规则的全部字段与计数器
  • 新增、修改、启用/停用、调整顺序和删除防火墙与 NAT 规则,按真实 .id 定位规则
  • 管理防火墙地址列表条目和静态 DNS 条目,并把 DHCP 租约固定为静态
  • 启用或停用接口,并通过只读的通用列举工具读取任意 RouterOS 配置路径
适用场景
适合让助手检查或调整 MikroTik 路由器配置的场景,例如审计防火墙与 NAT 规则、通过 DHCP 租约了解网络上有哪些设备,或做有针对性的规则修改,而不必通过 SSH 操作命令行。
运行要求
以 Python 包形式通过 uvx 在本地运行(stdio)。需要能访问路由器的 API 服务(默认 api-ssl 端口 8729,或明文 8728),并设置环境变量 MIKROTIK_HOST、MIKROTIK_USERNAME、MIKROTIK_PASSWORD,可选 MIKROTIK_PORT、MIKROTIK_TLS、MIKROTIK_TLS_FINGERPRINT、MIKROTIK_TIMEOUT。路由器用户所在用户组必须带有 api 策略。
安装前请注意
该服务器会修改甚至删除路由器上的实际配置:删除规则无法撤销,停用当前连接所经的接口会切断唯一的远程通路。关闭 MIKROTIK_TLS 会以明文发送路由器密码;未设置 MIKROTIK_TLS_FINGERPRINT 时自签名证书只被加密而未被认证。密码通过环境变量传入,建议使用专用的非管理员账号。

安装

在 SourceWeft 中

  1. 打开 控制台中的 MikroTik RouterOS,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

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

来源:README.md,提交 10d61a8

工具

34

system_info

System Info

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

无需输入参数。

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.

输入参数path必填

list_interfaces

List Interfaces

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

输入参数type_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.

输入参数enabled必填interface_id必填

list_ip_addresses

List IP Addresses

List configured IPv4 addresses and the interfaces they sit on.

无需输入参数。

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.

输入参数chainfamilyverboseinclude_dynamic

get_firewall_rule

Get Firewall Rule

Every field of one firewall rule, including counters.

输入参数familyrule_id必填

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.

输入参数logpsdportchain必填limitaction必填familycommentdisableddst_portprotocolsrc_port另有 21 个

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.

输入参数logpsdportchainlimitunsetactionfamilycommentrule_id必填dst_portprotocol另有 21 个

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.

输入参数familyenabled必填rule_id必填

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.

输入参数familyrule_id必填confirm_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.

输入参数familyrule_id必填before_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.

输入参数family

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.

输入参数limitfamilyaddresslist_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`.

输入参数familyaddress必填commenttimeoutlist_name必填

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.

输入参数familyentry_id必填confirm_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.

输入参数chainverboseinclude_dynamic

get_nat_rule

Get NAT Rule

Every field of one NAT rule, including counters.

输入参数rule_id必填

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.

输入参数logportchain必填action必填commentdisableddst_portprotocolsrc_portto_portslog_prefixdst_address另有 12 个

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.

输入参数logportchainunsetactioncommentrule_id必填dst_portprotocolsrc_portto_portslog_prefix另有 12 个

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.

输入参数rule_id必填before_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.

输入参数enabled必填rule_id必填

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.

输入参数rule_id必填confirm_comment

list_dhcp_leases

List DHCP Leases

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

输入参数searchactive_only

make_lease_static

Make DHCP Lease Static

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

输入参数commentlease_id必填

list_dns_static

List Static DNS

List static DNS entries and regex overrides.

无需输入参数。

add_dns_static

Add Static DNS Entry

Add a static DNS entry.

输入参数ttlnamecnameregexpaddresscommentmatch_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.

输入参数ttlnamecnameregexpaddresscommentdisabledentry_id必填match_subdomain

remove_dns_static

Remove Static DNS Entry

Delete a static DNS entry.

输入参数entry_id必填

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.

无需输入参数。

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.

无需输入参数。

list_routes

List Routes

List the IPv4 routing table.

输入参数active_only

get_logs

Get Logs

Read the device log, most recent last.

输入参数limittopicsearch

connectivity_check

Connectivity Check

Confirm the hub can reach and authenticate to this device.

无需输入参数。

版本历史

3
  1. v0.3.1最新Nov 13, 2026
  2. v0.3.0Sep 21, 2026
  3. v0.2.0Sep 16, 2026

评分

已满足适用检查项的 90%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分
  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分

其他 Router 集成