mikrotik-rest-mcp

English | Русский

MikroTik REST MCP

通过 REST API 为编码 Agent 提供对 RouterOS 7 设备的结构化访问能力的 MCP 服务——支持读取、筛选查询、受保护的写入、定时回滚保护、容器 shell 和文件传输。一个通过 stdio 运行的 MCP 服务。

专为实际运维工作打造：Agent 可以盘点路由器、比较防火墙/路由状态、操作容器、监控计数器并应用更改——所有可能造成破坏的操作都必须先经过人工确认。

功能

• 广泛的读取覆盖范围
  • 为常见集合（防火墙、路由、DHCP、DNS、接口、WireGuard、容器、计划任务、日志、系统资源）精选了约 60 个 get_* 工具。
  • 另外还有 200 多个 get_* 端点可通过同一过滤流程按名称调用——这些端点刻意不列出，以保持工具架构简洁。catalog_search 可帮助发现它们。
  • routeros_get 可直接接受任意 /rest/ 路径，还可使用 routeros_batch 在一次调用中并行读取最多 16 项。
• 强大的查询能力
  • 客户端 where 过滤器，支持 __contains、__in、__not、__gt、__gte、__lt、__lte、__startswith、__endswith。
  • fields 投影、sort_by、limit、compact（每项输出一行，可节省大量 token）。
  • 透传 RouterOS 原生 .proplist / .query，以便在服务端过滤。
• 受保护的变更操作
  • MIKROTIK_MODE=readonly：完全不注册变更／执行工具——协议接口本身为只读，而不只是受策略限制。
  • MIKROTIK_MODE=careful（默认）：被归类为有干扰性的操作会返回 requires_confirmation——Agent 将其转告用户，并在获得批准后使用 confirm: true 重新运行。在支持的情况下，MCP elicitation 会显示原生对话框。确认标志只是 UX 门槛，并非安全边界——真正限制 Agent 的是 RouterOS 账户权限。
  • 基于方法的策略：PUT 仅可用于已知集合，PATCH / DELETE 仅可用于 collection/<id> 项，POST 仅可用于明确列出的操作白名单（ping、traceroute、fetch、file/read、script/run、dns flush、backup/save、export、容器 shell——参见 catalog.py）。
  • MIKROTIK_STRICT_CONFIRM=1 会要求每项变更操作都经过确认。
  • MIKROTIK_MODE=yolo 会移除所有门槛，并可切换到单独的完全权限账户（MIKROTIK_YOLO_USERNAME / MIKROTIK_YOLO_PASSWORD_FILE）——仅适用于有人监督的自动化时段。
• 计划回滚保护（不是 RouterOS Safe Mode——可通过普通 REST 使用）
  • apply_safe 会对目标创建快照、启用路由器上的计划任务，然后应用变更。启用后，回滚不再依赖 MCP 进程或客户端持续运行——commit_safe 可在 window_seconds 内将其禁用。
  • 支持的方法：PATCH（恢复快照中已更改字段的值——非事务性，不检测并发编辑）和 DELETE（尽力重新创建；不保留列表位置和生成的字段——响应中会说明）。拒绝 PUT，因为只有在项目创建后才能知道其 .id。
  • 传输失败情况不明确时，会保持回滚启用，而不会静默将其禁用；如果禁用失败，commit_safe 会保留待处理记录，以便重试。
  • safe_status 会报告当前已启用的回滚。
• 容器与诊断
  • container_shell 可通过名称或 .id 在 RouterOS 容器内运行命令——默认关闭（MIKROTIK_ENABLE_CONTAINER_SHELL），在 careful 模式下需要确认，且通用的 routeros_write 路径无法绕过此标志。timeout_seconds 可为长时间运行的命令覆盖 REST 超时。
  • container_apply_safe / container_commit_safe——在容器内执行事务性 shell 命令：对 snapshot_paths 创建快照，运行变更操作，check_cmd 在失败时立即回滚，并由重复运行的 RouterOS 计划任务看门狗在未及时提交时恢复快照。每个容器只能有一个活动事务。
  • interface_traffic 会在采样时间窗口内测量实时 rx/tx bps 和 pps；routeros_watch 会比较多个采样点之间的数值字段——无需手动读取两次即可获得计数器增量。
  • run_ping、run_traceroute、run_fetch、run_wifi_monitor、describe_path（在编写过滤器前检查字段）。
• 带沙盒的文件操作
  • 在 RouterOS 端创建／读取／更新／重命名／删除文件，并支持分块执行 download_file / upload_file。
  • 默认关闭对主机文件系统的访问；MIKROTIK_ENABLE_LOCAL_FILES + MIKROTIK_LOCAL_ROOT 会将访问限制在单个目录内；传输上限为 8 MiB，且 download_file 需要设置 overwrite: true 才能替换现有本地文件。
• 密钥保护
  • 凭据来自 MIKROTIK_PASSWORD_FILE（推荐）或 MIKROTIK_PASSWORD。
  • 每个响应都会经过清理器，遮蔽形如 password / secret / psk / token / private-key 的字段（设置 MIKROTIK_REDACT=0 可禁用）。遮蔽依据字段名称进行——无法可靠检测自由格式文本（注释、脚本正文、日志行、文件内容）中嵌入的密钥。
  • 每个工具都带有工具注解（readOnlyHint、destructiveHint、idempotentHint、openWorldHint），以便客户端执行自己的策略。

要求

• Python 3.10+（基于 3.13 开发）。
• RouterOS 7.1+，且 REST 可访问（已在 7.24.5、hAP ax³ 上完成集成测试，涵盖 REST、容器、调度器回滚和文件操作）。建议通过 www-ssl 使用 HTTPS；通过 www 使用纯 HTTP 需要 RouterOS 7.9+，且仅应在隔离网络中使用——REST 使用 Basic auth，凭据会以明文形式在网络中传输。
• 只读使用时，RouterOS 用户需要 read + api + rest-api 权限。执行变更/诊断时添加 write + test 权限，使用文件工具（download_file、/file/read）时添加 ftp 权限。脚本条目有自己的 policy 属性——账号只需 write 权限即可运行脚本，且无法运行权限范围超出自身权限的脚本。

安装

pipx install mikrotik-rest-mcp-server   # or: uvx mikrotik-rest-mcp-server

这会提供 mikrotik-rest-mcp-server 控制台脚本。开发时：使用 git clone，然后运行 pip install -e .

配置

将 MCP 客户端指向此服务：

{
  "mcpServers": {
    "mikrotik_rest": {
      "command": "mikrotik-rest-mcp-server",
      "env": {
        "MIKROTIK_BASE": "https://192.168.88.1",
        "MIKROTIK_USERNAME": "mcp-agent",
        "MIKROTIK_PASSWORD_FILE": "/path/to/password-file"
      }
    }
  }
}

完整变量列表（模式、功能标志、超时、TLS 验证）请参阅 .env.example。

推荐的 RouterOS 账号

# ops account — reads, config writes, diagnostics; no user/policy management,
# no sensitive fields, no reboot
/user group add name=agent policy=read,write,api,rest-api,test,ftp
/user add name=mcp-agent group=agent password=<random>

# monitoring-only account (pair with MIKROTIK_MODE=readonly)
/user group add name=monitor policy=read,api,rest-api,test

对于 yolo 模式，请在 full 组中创建第二个账号，并通过 MIKROTIK_YOLO_* 配置使用该账号。如果不需要文件工具，可以省略 ftp。

与 Agent 配合使用

Agent 采用的典型流程：

get_dhcp_leases {compact: true}                     → quick device list
routeros_batch {requests: [...]}                    → status in one call
describe_path {path: "/rest/interface/ethernet"}    → field names before filtering
interface_traffic {name: "ether1", seconds: 2}      → live throughput
routeros_watch {path: ..., diff: true}              → counter deltas
routeros_write {method: "PATCH", ...}               → routine config edit
routeros_write {method: "DELETE", ...}              → stops for confirmation
apply_safe {method: "PATCH", path: "…/<.id>", window_seconds: 60}
                                                    → rollback armed on router; commit_safe to keep

run_script_inline 会创建一个临时 RouterOS 脚本、运行该脚本，然后将其删除（谨慎模式下始终会确认）。container_shell 和主机文件传输需要启用相应的可选标志。

目录结构

src/mikrotik_rest_mcp/
  client.py      — REST transport, TLS, env config
  catalog.py     — endpoint/tool tables (pure data)
  policy.py      — risk tiers, confirmation gate, mutation allowlist
  output.py      — secret redaction, filters, compact serialization
  files.py       — local file sandbox + router file helpers
  safe_apply.py  — snapshot/rollback machinery
  server.py      — tool list, dispatch, resources, entrypoint

测试

pytest tests/

单元测试无需路由器即可运行（REST 调用均已模拟）。

安全

请参阅 SECURITY.md。不要将此工具用于你无权管理的路由器；请将 yolo 视为已上膛的枪，将 container_shell 视为远程代码执行（因为它确实如此）。