内容
<div align="center">
<img src="assets/logo.svg" alt="@usex/mikrotik-mcp" width="440" />
<p><strong>一款原生的Bun MCP服务器，能将一个或多个MikroTik路由器变成AI可驱动的706工具。</strong><br/>
防火墙 · 路由 · DHCP/DNS · 无线 · QoS · 以及完整的VPN套件 — 通过SSH，具有事务安全模式。</p>
<p>
<a href="LICENSE"><img alt="许可证：MIT" src="https://img.shields.io/badge/License-MIT-7C3AED.svg"></a>
<img alt="运行时：Bun" src="https://img.shields.io/badge/runtime-Bun%20%E2%89%A5%201.3-06B6D4.svg">
<img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-6366F1.svg">
<img alt="MCP" src="https://img.shields.io/badge/MCP-706%20tools-1F2937.svg">
<a href="docs/"><img alt="文档" src="https://img.shields.io/badge/docs-reference-7C3AED.svg"></a>
</p>
</div>
---
`@usex/mikrotik-mcp` 将 **MikroTik RouterOS** 暴露为 **706个Model Context Protocol工具**，跨越111个模块，因此AI客户端（Claude Desktop，Claude Code，任何MCP客户端）可以用纯语言读取和配置您的路由器。它通过 **SSH** 与设备通信 — 无需代理，无需在RouterOS上安装API包 — 在 **Bun** 上运行，并针对Zod模式验证每个工具调用。
每个工具都带有 **风险注解** （读/写/破坏性），因此客户端可以控制哪些运行，风险更改可以包装在 **安全模式** 中 — RouterOS将其保存在内存中，如果会话断开，则自动恢复，因此您不会锁定自己。
```jsonc
// claude_desktop_config.json
{
"mcpServers": {
"mikrotik": {
"command": "mikrotik-mcp",
"env": {
"MIKROTIK_HOST": "192.168.88.1",
"MIKROTIK_USERNAME": "admin",
"MIKROTIK_PASSWORD": "your-password",
},
},
},
}
```
> _"显示防火墙输入链，然后在安全模式下阻止来自WAN的SSH。"_
> _"建立到203.0.113.5的IKEv2站点到站点隧道，用于192.168.20.0/24。"_
> _"为什么VLAN 50无法访问互联网？"_
## 为什么它与众不同
- 🧰 **广度** — 706工具涵盖整个设备：L2（桥接，VLAN，无线，PoE），L3（寻址，路由，DHCP，DNS），安全（防火墙，NAT，地址列表，证书），QoS（队列），以及系统操作（用户，日志，备份，调度器）。
- 🔐 **完整的VPN套件** — WireGuard，IPsec（IKEv1/IKEv2），L2TP，PPTP，SSTP，OpenVPN，以及GRE/IPIP/EoIP/VXLAN隧道。具有为您选择合适的 `choose-vpn-solution` 提示。参见 **[VPN指南](docs/vpn-guide.md)**。
- 🛟 **安全模式** — 一个真正的事务窗口（`enable_safe_mode` → 更改 → `commit_safe_mode`/`rollback_safe_mode`）由持久的SSH会话支持。断开连接时自动恢复。
- 🚦 **风险注解工具** — `readOnlyHint` / `destructiveHint` 让客户端自动批准读取并在写入时提示。
- 🧱 **默认防止注入** — 命令生成器引用/转义每个值，因此像 `LAN; /system reset` 这样的主机名永远不会分成第二个命令。
- 🖧 **多个设备** — 定义命名路由器，AI每次调用一个（验证的 `device` 参数）。配置 **双端隧道** 从一个对话中。参见 **[docs/multi-device.md](docs/multi-device.md)**。
- 🪜 **SSH跳转主机** — 通过 `jumpVia` （ProxyJump/堡垒）到达没有暴露端口的路由器 — 命令，安全模式和文件上传都通过跳转。无需新的WAN端口。
- ⚡ **连接池** — 每个设备一个持久的SSH会话，在工具调用中共用。节省每个命令的~200-500毫秒握手时间（通过跳转主机双倍）。空闲连接在30秒后自动关闭。
- 🤖 **引导提示** — 9个内置工作流（强化，诊断，访客Wi-Fi，VPN，跨设备隧道，备份和文档），将意图转化为工具调用。
## 快速开始
```bash
# 1. 安装（需要Bun ≥ 1.3 — https://bun.sh）
bun add -g @usex/mikrotik-mcp
# 2. 将其指向您的路由器并验证SSH连接
MIKROTIK_HOST=192.168.88.1 MIKROTIK_USERNAME=admin MIKROTIK_PASSWORD=•••• \
mikrotik-mcp auth-check
# 3. 列出目录（名称 · 风险 · 标题）
mikrotik-mcp tools
# 4. 运行它（默认stdio — 将其连接到您的MCP客户端）
mikrotik-mcp serve
```
**在没有AI客户端的情况下试用** — 使用官方 [MCP Inspector](docs/inspector.md) 对抗服务器（从源代码）打开：
```bash
bun run inspect # 打开Inspector UI以浏览/运行所有706个工具
```
**更喜欢SSH密钥而不是密码？** 将服务器指向密钥文件 — 并在密钥加密时添加口令：
```bash
MIKROTIK_HOST=192.168.88.1 MIKROTIK_USERNAME=admin \
MIKROTIK_KEY_FILENAME=~/.ssh/id_ed25519 \
MIKROTIK_KEY_PASSPHRASE=•••• \
mikrotik-mcp auth-check # 打印"Auth mode: SSH key"
```
密钥（文件通过 `--key-filename` 或内联PEM通过 `--private-key`）优先于密码。完整的配置参考： **[docs/configuration.md](docs/configuration.md)**。
### 从源代码
```bash
git clone https://github.com/mikrotik-mcp/mikrotik-mcp && cd mikrotik-mcp
bun install
bun run start # 从源代码提供服务
bun run build # 打包到dist/
```
## 工具目录
**111个模块中的706个工具。** 完整的，始终更新的参考（每个工具的参数 + 风险）从源代码生成： **[docs/tools-reference.md](docs/tools-reference.md)**。
| 组 | 工具 | 模块 |
| ------------------------ | ----: | ---------------------------------------------------------------------------------------------------------- |
| **接口** | 41 | 接口，VLAN，桥接，无线，PoE |
| **寻址和路由** | 46 | IP地址，IP池，路由，DHCP，DNS |
| **动态路由** | 99 | 路由器ID，设置，表格，规则，下一跳，过滤器，BFD，BGP，OSPF，RIP，PIM-SM，IGMP代理，GMP，RPKI |
| **安全** | 34 | 防火墙过滤器，NAT，地址列表，证书，IP服务 |
| **VPN和隧道** | 96 | WireGuard，IPsec，PPP，L2TP，PPTP，SSTP，OpenVPN，GRE/IPIP/EoIP/VXLAN |
| **QoS** | 19 | 队列类型，队列树，简单队列 |
| **系统和操作** | 102 | 系统，网络工具，调度器/脚本，用户，日志，备份，安全模式 |
## VPN和隧道 — 专家覆盖
每个MikroTik VPN技术，按照RouterOS实际分层（基于PPP的VPN共用一个 `/ppp` 后端供用户和寻址）：
| 需要 | 使用 | 使用 |
| ----------------------------------- | ----------------------- | -------------------------------------------------------------------------------------- |
| MikroTik ↔ MikroTik，现代客户端 | **WireGuard** | `create_wireguard_interface`，`add_wireguard_peer`，`generate_wireguard_client_config` |
| 互操作站点到站点 / 原生IKEv2 | **IPsec** | `create_ipsec_{profile,peer,identity,proposal,policy}`，`get_ipsec_active_peers` |
| 内置OS VPN客户端 | **L2TP/IPsec** | `set_l2tp_server`，`create_ppp_secret`，`create_ppp_profile` |
| 通过限制性防火墙 | **SSTP** （TLS） | `set_sstp_server`，`create_sstp_client` |
| 跨平台OpenVPN | **OpenVPN** | `set_ovpn_server`，`create_ovpn_client` |
| 路由 / L2桥接站点之间 | **GRE/IPIP/EoIP/VXLAN** | `create_gre_tunnel`，`create_eoip_tunnel`，`create_vxlan_tunnel` |
不确定？调用 **`choose-vpn-solution`** 提示，服务器推荐一个并概述构建。详情： **[docs/vpn-guide.md](docs/vpn-guide.md)**。
## 管理多个设备
给每个路由器一个名称，AI可以在一个对话中驱动它们 — 正是您需要 **设置两个MikroTik站点之间的隧道并从两端测试**。 将服务器指向JSON文件（或 `MIKROTIK_DEVICES`）：
```jsonc
// devices.json
{
"defaultDevice": "site-a",
"devices": {
"site-a": { "host": "203.0.113.10", "username": "admin", "keyFilename": "/keys/site-a" },
"site-b": { "host": "198.51.100.20", "username": "admin", "password": "••••" },
},
}
```
```bash
mikrotik-mcp serve --config ./devices.json
mikrotik-mcp devices # site-a（默认）· site-b
mikrotik-mcp auth-check # 探测每个设备
```
当配置了多个设备时， **每个工具都获得一个可选的 `device` 参数** （您命名的验证枚举）；省略它以使用默认值。 AI使用 `list_mikrotik_devices` 发现名称， **安全模式按设备** ，因此每个路由器独立提交。 **`setup-tunnel-between-sites`** 提示驱动整个两端流程。完整指南： **[docs/multi-device.md](docs/multi-device.md)**。
```jsonc
// AI调用针对特定路由器：
create_wireguard_interface { "device": "site-a", "name": "wg-to-b", "listen_port": 13231 }
```
**在堡垒后面？** 通过另一个（OpenSSH样式的ProxyJump）到达没有暴露的SSH端口的路由器 — `jumpVia` 命名一个配置的设备来隧道通过；命令，安全模式和SFTP上传都通过跳转：
```jsonc
"home-ax3": { "host": "10.10.30.100", "username": "admin", "jumpVia": "hex" }
```
堡垒路由器需要启用SSH TCP转发（ `/ip ssh set forwarding-enabled=local`）。参见 **[docs/multi-device.md](docs/multi-device.md#ssh-jump-hosts-bastion--proxyjump)**。
## 内置提示
MCP **提示** 是一键式引导工作流。该服务器自带9个 — 以Markdown编写在 [`prompts/`](prompts/)中，因此您可以编辑或添加自己的，无需修改代码：
`harden-router` · `diagnose-connectivity` · `setup-guest-wifi` ·
`choose-vpn-solution` · `setup-wireguard-vpn` · `setup-ipsec-site-to-site` ·
`setup-l2tp-ipsec-roadwarrior` · `setup-tunnel-between-sites` · `backup-and-document`
参见 **[docs/prompts.md](docs/prompts.md)**。
## 传输
| 传输 | 何时 | 运行 |
| ------------------- | --------------------------------- | ---------------------------------------------------------------- |
| **stdio** （默认） | Claude Desktop，本地MCP客户端 | `mikrotik-mcp serve` |
| **streamable-http** | 远程/共享，代理后面 | `mikrotik-mcp serve --transport streamable-http --mcp-port 8000` |
| **sse** | 旧HTTP客户端 | `mikrotik-mcp serve --transport sse` |
HTTP传输公开 `POST /mcp` 和 `GET /health` 检查，具有与您的绑定主机自动协调的DNS重新绑定保护。参见
**[docs/transports.md](docs/transports.md)**。
## SSH连接池
默认情况下，服务器为 **每个设备保留一个持久的SSH连接** ，并为每个工具调用打开一个全新的执行通道 — 消除了每次命令的~200-500毫秒握手开销。通过跳转主机节省的费用是双倍的（避免两次握手）。空闲连接在30秒后自动关闭。
```bash
# 禁用连接池（恢复到每个调用一次）
MIKROTIK_SSH__KEEP_ALIVE=false mikrotik-mcp serve
# 调整空闲超时（毫秒）
mikrotik-mcp serve --ssh-idle-timeout 60000
```
在JSON配置文件中：
```jsonc
{
"ssh": {
"keepAlive": true, // 默认 — 设置为false以禁用
"keepAliveInterval": 10000, // SSH keepalive包间隔（毫秒）
"idleTimeout": 30000, // 空闲连接后关闭（毫秒）
},
}
```
连接池仅限SSH；MAC-Telnet设备始终使用一次性连接。安全模式仍使用其自己的专用持久会话。
## 安全模式
```text
enable_safe_mode → （进行更改）→ commit_safe_mode # 持久
→ rollback_safe_mode # 丢弃
```
激活时，每个更改都保存在内存中；如果SSH会话断开（例如，防火墙规则将您锁定），RouterOS会自动恢复。会话期间发出的命令通过相同的持久会话路由。参见 **[docs/safe-mode.md](docs/safe-mode.md)**。
## 配置
连接和传输设置来自 `MIKROTIK_*` 环境变量或匹配的CLI标志（最高优先级最后：默认值 → 环境变量 → 标志）。
| 变量 | 标志 | 默认值 | 目的 |
| ----------------------------- | -------------------- | ----------- | ---------------------------------------------------------------------------------------------------- |
| `MIKROTIK_HOST` | `--host` | `127.0.0.1` | RouterOS主机 |
| `MIKROTIK_USERNAME` | `--username` | `admin` | SSH用户 |
| `MIKROTIK_PORT` | `--port` | `22` | SSH端口 |
| `MIKROTIK_PASSWORD` | `--password` | — | SSH密码 _(或使用密钥 →)_ |
| `MIKROTIK_KEY_FILENAME` | `--key-filename` | — | SSH私钥文件路径 |
| `MIKROTIK_PRIVATE_KEY` | `--private-key` | — | 内联私钥（PEM） |
| `MIKROTIK_KEY_PASSPHRASE` | `--key-passphrase` | — | 加密密钥的口令 |
| `MIKROTIK_JUMP_HOST` | `--jump-host` | — | SSH堡垒隧道通过（[跳转主机](docs/multi-device.md#ssh-jump-hosts-bastion--proxyjump）） |
| `MIKROTIK_CONFIG_FILE` | `--config` | — | JSON命名设备文件 ([多设备](docs/multi-device.md)) |
| `MIKROTIK_DEVICES` | `--devices` | — | 内联JSON命名设备 |
| `MIKROTIK_MCP__TRANSPORT` | `--transport` | `stdio` | `stdio` / `streamable-http` / `sse` |
| `MIKROTIK_MCP__PORT` | `--mcp-port` | `8000` | HTTP绑定端口 |
| `MIKROTIK_SSH__KEEP_ALIVE` | `--ssh-keep-alive` | `true` | SSH连接池（跨工具调用重用连接） |
| `MIKROTIK_SSH__IDLE_TIMEOUT` | `--ssh-idle-timeout` | `30000` | 空闲连接后关闭（毫秒） |
| `MIKROTIK_DASHBOARD__ENABLED` | `--dashboard` | `false` | 实时可观察性仪表板（[docs](docs/observability.md） |
完整表格（包括HTTP主机，允许列表，超时， `MIKROTIK_LOG_LEVEL`）：**[docs/configuration.md](docs/configuration.md)**.
### 可观察性仪表板（可选）
仅限localhost的Web仪表板，拦截）
```bash
mikrotik-mcp serve --dashboard # → http://127.0.0.1:9090
```
参见 **[docs/observability.md](docs/observability.md)**.
## 超出目录
在范围内的工具之上，服务器提供更高级别的工作流：
- **[变更计划和试运行](docs/change-plan.md)** — 以terraform风格的计划预览预期命令（风险评分，锁定感知，安全有序），然后`apply_plan`在安全模式下运行它们，显示确切的`/export`差异，如果设备仍然可达，则提交（自动恢复锁定）。
- **[配置快照](docs/config-snapshots.md)** — 在主机上存储`/export`快照，并**时间旅行**任意两个或一个与实时设备的对比。
- **[防火墙审计](docs/firewall-audit.md)** — `firewall_audit`查找阴影，过度宽泛，缺少默认丢弃，重复和死亡规则，按风险评分，在MCP应用主机中具有一键式修复。
- **[分组捕获工作室](docs/packet-capture.md)** — 将镜像分组流式传输到主机，在仪表板中实时解码，并导出`.pcap`。
- **[发现](docs/discovery.md)** — `bun run discover`通过MAC（MNDP）列出局域网中的MikroTik设备；仪表板绘制实时**拓扑图**。
- **[配置工作室](docs/config-studio.md)** — 在仪表板中编辑配置JSON，具有自动完成，验证和安全应用自动回滚。
## 架构
`schemas/` 目录下提供了机器可读的 JSON Schemas，这些 Schemas **从 TypeScript 源代码生成**（`bun run gen:schemas`），因此它们永远不会过时：
- `schemas/tool-catalog.json` — 包含每个工具的风险、描述和输入 Schema
- `schemas/tools/<name>.json` — 每个工具的输入 Schema
- `schemas/config.schema.json` — 运行时配置
## 文档
| 文档 | 介绍 |
| ------------------------------------------------------------- | ----------------------------------------------------------- |
| [快速入门](docs/getting-started.md) | 安装、验证、首次运行 |
| [配置](docs/configuration.md) | 所有环境变量和标志 |
| [多设备管理](docs/multi-device.md) | 管理多个路由器；每次调用的目标 |
| [连接客户端](docs/connecting-clients.md) | Claude Desktop、stdio、HTTP |
| [传输方式](docs/transports.md) | stdio / HTTP / SSE, DNS 重绑定 |
| **[可观察性](docs/observability.md)** | 实时仪表盘：实时信息流 + 分析，SQLite |
| [安全模式](docs/safe-mode.md) | 事务性更改 |
| **[变更计划和预演](docs/change-plan.md)** | 预览命令，应用确切的差异 + 自动回滚 |
| **[配置快照](docs/config-snapshots.md)** | `/export` 快照 + 时间旅行差异 |
| **[防火墙审计](docs/firewall-audit.md)** | 被遮蔽/宽泛/无效的规则，风险评分 |
| **[数据包捕获工作室](docs/packet-capture.md)** | 实时 TZSP 捕获 + pcap 导出 |
| **[发现](docs/discovery.md)** | `bun run discover`，MNDP 邻居，拓扑图 |
| **[配置工作室](docs/config-studio.md)** | 在仪表盘中编辑配置，带自动补全 |
| **[VPN 指南](docs/vpn-guide.md)** | 每种隧道类型 + 如何构建它 |
| [提示](docs/prompts.md) | 9 个引导式工作流 |
| [架构](docs/architecture.md) | 构建方式 |
| [安全](docs/security.md) | 凭证，风险控制 |
| [工具参考](docs/tools-reference.md) | 完整的生成目录 |
| [MCP 检查器](docs/inspector.md) | 在 UI 或 CLI 中测试工具/提示 |
| [开发](docs/development.md) · [Docker](docs/docker.md) | 构建、测试、部署 |
## 开发
```bash
bun run test:types # tsc --noEmit
bun test # 单元测试
bun run gen # 从源代码重新生成 schemas/ + docs/tools-reference.md
bun run build # 打包到 dist/
```
参见 **[docs/development.md](docs/development.md)** 和 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 安全
通过您提供的凭证与 RouterOS 进行 SSH 通信；不会将任何信息发送到其他地方。工具值会被引用/转义，以防止控制台命令注入。破坏性和危险的工具会被注解，以便客户端可以要求确认，并且一个关于容器中纯文本密码的警告会促使您使用密钥文件或密码。详情： **[docs/security.md](docs/security.md)**。请仅将此指向您有权管理的设备。
## 许可证
[MIT](LICENSE)。自由使用。无担保。
---
<div align="center">
<img src="assets/logo-icon.svg" width="56" alt="" /><br/>
由 <a href="https://github.com/ali-master">Ali Torki</a> 倾情打造 ❤️
</div>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器