MikroMCP

MikroMCP

面向 AI 的 MikroTik RouterOS 和 SwOS 网络自动化。 MikroMCP 将 RouterOS 路由器和 SwOS 交换机作为具有类型定义且可审计的 Model Context Protocol 服务公开，让 Claude、Cursor、Codex 和其他 MCP 客户端能够通过自然语言检查、诊断并安全地管理 MikroTik 设备。

MikroMCP 诞生的原因是，直接访问路由器 CLI 并不适合作为 AI Agent 的抽象层。RouterOS 功能强大，但让大模型对生产网络设备临场编写 shell 命令存在风险。MikroMCP 为 Agent 提供受控的工具接口：严格的 schema、幂等写入、dry-run 预览、按路由器设置的熔断器、重试策略、RBAC、审计日志、快照，以及支持回滚的变更工作流。

一句话概括： MikroMCP 将 MikroTik RouterOS 转变为面向生产环境的 MCP 控制平面，用于 AI 基础设施、DevOps 自动化和现代路由器管理。

---

快速开始

单路由器 stdio 部署只需完成这些设置。有关独立二进制文件、Docker、HTTP/SSE 模式、RouterOS API 前置条件，以及完整的 15 分钟演练，请参阅 入门指南。

---

功能展示

类别	MikroMCP 涵盖的内容
🧭 路由器管理	系统状态、时钟、重启、软件包、文件、脚本、计划任务、容器
🌐 网络操作	接口、VLAN、IP 地址、DHCP 租约、DNS 静态记录、网桥端口、WiFi 客户端
🔥 防火墙与策略	过滤/NAT 规则、mangle 规则、地址列表、路由表、路由规则
🛰️ 路由可见性	静态路由、路由表、BGP 对等体、OSPF 邻居
🔀 SwOS 交换机	实验性功能。 通过逆向工程实现的 .b HTTP API 操作 MikroTik SwOS 和 SwOS Lite 交换机（deviceType: "swos"）：端口链路、PoE、SFP 诊断、带固件兼容性检查的受保护整块数据写入、以单个 YAML 文档形式处理完整交换机配置（导出、试运行、应用）、备份和固件升级
🔐 安全访问	HTTP bearer 身份验证、bcrypt 令牌哈希、RBAC、路由器/工具限制、确认令牌
🧪 诊断	由路由器发起的 ping、traceroute、torch、日志筛选、受保护的 SSH 命令执行
🛡️ 变更安全	试运行、幂等写入、快照、写入日志、plan_changes、apply_plan、rollback_change
⚙️ 生产环境行为	读取工具重试、按路由器隔离的熔断器、关联 ID、结构化日志、审计日志
🤖 适用于 AI Agent	面向用户的易读响应，以及用于推理、串联和自动化的结构化 JSON 内容；服务器在 MCP 初始化时通过 instructions 字符串进行声明，让客户端自动配置；单路由器配置可选用 routerId，通过 MIKROMCP_DEFAULT_ROUTER 解析；提供使用技能，帮助在 Claude Code 中安全、按引导使用工具
🧩 MCP 兼容性	适用于桌面客户端的 stdio，以及适用于远程或服务型客户端的 Streamable HTTP 和旧版 SSE

总计 133 个类型化工具 — 在 可用工具 中查看完整目录，其中包含参数、默认值和可直接复制粘贴的示例提示词。

---

演示

使用方法

Claude 的评审

---

真实场景使用示例

路由器检查

Use MikroMCP to inspect core-01. Summarize system resources, RouterOS version,
running interfaces, active routes, DNS settings, and recent warning/error logs.
Flag anything that looks operationally risky.

防火墙管理

List firewall filter and NAT rules on edge-01. Identify disabled rules,
overlapping port forwards, broad accept rules, and anything without comments.
Do not change anything yet.

安全变更静态路由

Dry-run a route on core-01 for 10.20.0.0/16 via 192.168.88.1 in the main table.
Show the exact planned diff and tell me whether an existing route conflicts.

WireGuard 操作

Show WireGuard peers on branch-02. Sort by last handshake age and flag peers
that have not handshaken recently or have no transfer counters.

接口诊断

Check interface health on edge-01, then run ping and traceroute from the router
to 1.1.1.1. If packet loss is present, use torch on the WAN interface for a
short traffic snapshot.

计划 / 应用 / 回滚工作流

Create a change plan that adds a DNS record and a firewall address-list entry
on edge-01. Use dry-run first, explain the plan, then wait for approval before
applying anything.

---

MikroMCP 对 AI Agent 的价值

MCP 为大模型提供了调用工具的标准方式。MikroMCP 将网络操作转化为描述清晰、机器可读且支持权限控制的操作，让 RouterOS 成为高质量的 MCP 目标。

AI 助手可以使用 MikroMCP 来：

• 检查路由器状态，无需记忆 RouterOS 命令语法。
• 在接口、路由、防火墙规则、日志和诊断工具之间串联调用。
• 同时返回便于运维人员阅读的摘要和供后续推理使用的结构化 JSON。
• 在变更前预览，并准确说明将会发生什么。
• 遵循工具级授权、路由器范围限制、维护时段和确认关卡。

---

常见问题

什么是 MikroMCP？

MikroMCP 是一款开源的 Model Context Protocol（MCP）服务，提供 133 个类型化、可审计的工具来操作 MikroTik RouterOS — 让 AI 助手能够通过自然语言检查、诊断并安全地操作路由器，而不必临时拼凑 CLI 命令。

MikroMCP 与 RouterOS API 的比较

RouterOS REST/API 提供的是原始端点。MikroMCP 将这些端点封装为经过架构验证、具备幂等性且支持试运行的工具，并提供 RBAC、审计日志、快照和回滚功能——这是大模型在接触生产设备前所需的安全保障。

MikroMCP 与 SSH 自动化的比较

MikroMCP 不再依赖脆弱的 SSH 脚本抓取 CLI 输出，而是返回结构化、类型明确的结果，并提供确认关卡和针对每台路由器的熔断器。仅在 REST 无法访问时才使用 SSH——用于 ping 和受保护的 run_command。

用于 Claude Code 的 MikroMCP

MikroMCP 通过 stdio 和 HTTP/SSE 使用 MCP 协议，因此 Claude Code 和 Claude Desktop 可以直接操作 RouterOS。搭配内置的使用技能，即可开展安全、循序渐进的工作流。

用于 Codex 的 MikroMCP

Codex 通过标准 MCP 协议连接 MikroMCP——请参阅连接到 AI 助手。

用于 Cursor 的 MikroMCP

Cursor 将 MikroMCP 作为 MCP 服务（stdio 或 HTTP）连接，无需离开编辑器即可检查和管理 MikroTik 路由器。

用于 OpenClaw 的 MikroMCP

任何兼容 MCP 的客户端（包括 OpenClaw）都可以使用 MikroMCP；将其配置为 stdio 或 HTTP MCP 服务即可。

RouterOS AI 自动化指南

从入门指南开始安装和连接，然后使用使用技能和可用工具，通过 AI 助手安全地自动化管理 RouterOS。

网络工程师的最佳 MCP 服务

MikroMCP 专为 MikroTik/RouterOS 操作打造，具备生产级安全性——试运行、回滚、审计和 RBAC——因此是网络工程师采用 AI 工具时的优选 MCP 工具。

---

文档

README 有意保持简短。以下内容均已在 wiki 中详细说明：

资源	用途
快速入门	安装（npm、二进制文件、Docker）、配置并在 15 分钟内完成连接
RouterOS API 设置	启用 REST API、创建用户、配置 TLS 和防火墙
配置	路由器注册表、凭据、所有环境变量
运行	运行命令、HTTP/SSE 传输、故障排除
连接到 Claude Desktop	在 Claude Desktop 中注册 MikroMCP
连接到 AI 助手	Claude Code、Cursor、Codex、HTTP/Docker/systemd
使用技能	安装 MikroMCP 使用技能，让助手安全地调用工具
可用工具	全部 133 个工具——参数和提示词示例
架构	系统层、请求管线、身份验证模型
错误处理	错误类别、重试引擎、熔断器
安全	威胁模型、加固清单、漏洞报告
开发	项目结构、测试、MCP Inspector 工作流
贡献	添加工具、编码规范、PR 检查清单
路线图 · ROADMAP.md	已交付的里程碑和指导原则

---

贡献

欢迎提交问题、错误报告、工具请求、文档改进和拉取请求。

适合初次贡献的事项：

• 为尚未覆盖的 RouterOS 功能添加只读工具。
• 添加截图、演示 GIF 或拓扑图。
• 扩展测试，涵盖 RouterOS 响应规范化和幂等性边缘情况。
• 协助验证 RouterOS 版本在实际 MikroTik 设备和 CHR 上的兼容性。

开发规范：

• 使用 TypeScript 严格模式；ESM 导入须带 .js 扩展名
• Zod 模式使用 .strict()；写入工具须支持幂等性和 dryRun
• 使用 MikroMCPError 表示领域错误；为每个工具编写有针对性的 Vitest 测试

进行重大更改前，请先提交问题，以便维护者就范围达成一致。

致谢

• @f0086 — 支持 SwOS / SwOS Lite 交换机（v1.9.0），使 MikroMCP 首次扩展到 RouterOS 之外。
• @karamble — 全面支持 SwOS（v1.14.0）：完整的 SwOS 方言、整台交换机配置应用、备份、固件升级、密码更改以及绑定到交换机的密钥。

---

安全

MikroMCP 会控制真实的网络设备——请将其视为运维系统：使用权限最小化的 RouterOS 用户、验证 TLS（或固定指纹）、仅将凭据存放在 ~/.mikromcp/.env 中、使用范围受限的 RBAC 身份，并在多人共用时启用审计日志。完整的加固清单和漏洞报告流程请参阅安全页面。

---

社区与支持

• ⭐ 如果 MikroMCP 对你的 MikroTik 或 MCP 工作流有所帮助，请为仓库点 Star。
• 🍴 Fork 仓库，添加你的网络所依赖的 RouterOS 功能。
• 🧵 如有错误、功能请求、兼容性说明或文档缺漏，请创建 issue。

---

许可证

MikroMCP 基于 MIT 许可证发布。