内容
<div align="center">
<img src="assets/logo.svg" alt="" width="440" />
<p><strong>一款原生的Bun MCP服务器，将一个或多个MikroTik路由器变成AI可驱动的640种工具。</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-640%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** 暴露为 **640种Model Context Protocol工具**，跨越51个模块，因此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无法访问互联网？*
## 为什么它与众不同
- 🧰 **广度** — 640种工具涵盖整个设备：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指南** 。
- 🛟 **安全模式** — 一个真正的事务窗口（`enable_safe_mode` → 更改 → `commit_safe_mode`/`rollback_safe_mode`），由持久的SSH会话支持。断开连接时自动恢复。
- 🚦 **风险注解工具** — `readOnlyHint` / `destructiveHint` 允许客户端自动批准读取并提示写入。
- 🧱 **构造中防止注入** — 命令生成器引用/转义每个值，因此像 `LAN; /system reset` 这样的主机名永远不会分裂成第二个命令。
- 🖧 **多设备** — 定义命名路由器，AI针对每个调用的目标（一个验证的`device`参数）。配置 **隧道的两端** 来自一个对话。请参阅 **文档/多设备.md** 。
- 🤖 **引导提示** — 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以浏览/运行所有640种工具
```
**更喜欢SSH密钥而不是密码？** 将服务器指向密钥文件 — 如果密钥已加密，请添加口令：
```bash
MIKROTIK_HOST=192.168.88.1 MIKROTIK_USERNAME=admin \
MIKROTIK_KEY_FILENAME=~/.ssh/id_ed25519 \
MIKROTIK_KEY_PASSPHRASE=•••• \
mikrotik-mcp auth-check # 打印"身份验证模式：SSH密钥"
```
密钥（文件通过`--key-filename`或内联PEM通过`--private-key`）优先于密码。完整的配置参考： **[文档/配置.md](docs/configuration.md)**。
### 从源代码
```bash
git clone https://github.com/ali-master/mikrotik-mcp && cd mikrotik-mcp
bun install
bun run start # 从源代码提供服务
bun run build # 捆绑到dist/
```
## 工具目录
**640种工具，跨越51个模块。** 完整的、始终最新的参考（每个工具的参数+风险）从源代码生成： **[文档/工具参考.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`** 提示，服务器推荐一个并概述构建。详情： **[文档/VPN指南.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`** 提示驱动整个双端流程。完整指南： **[文档/多设备.md](docs/multi-device.md)**。
```jsonc
// AI调用针对特定路由器的工具：
create_wireguard_interface { "device": "site-a", "name": "wg-to-b", "listen_port": 13231 }
```
## 内置提示
MCP **提示** 是一键式引导工作流。该服务器自带9种 — 在 [`提示/`](prompts/) 中以Markdown编写，因此您可以编辑或添加自己的内容而无需修改代码：
`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`
请参阅 **[文档/提示.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重新绑定保护，与您的绑定主机自动协调。请参阅 **[文档/传输.md](docs/transports.md)**。
## 安全模式
```text
enable_safe_mode → （进行更改）→ commit_safe_mode # 持久
→ rollback_safe_mode # 丢弃
```
在活动期间，每个更改都保存在内存中；如果SSH会话断开（例如，防火墙规则锁定您），RouterOS会自动恢复更改。在窗口期间发出的命令通过相同的持久会话路由。请参阅 **[文档/安全模式.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_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_DASHBOARD__ENABLED` | `--dashboard` | `false` | 实时可观察性仪表板（[文档](docs/observability.md)) |
完整表格（包括HTTP主机，允许列表，超时，`MIKROTIK_LOG_LEVEL`）： **[文档/配置.md](docs/configuration.md)**。
### 可观察性仪表板（可选）
一个仅限localhost的Web仪表板，拦截 **每个** 工具调用LLM进行的操作 — 输入/输出的实时馈送（秘密已编辑），延迟百分比，错误率和每个工具/风险/设备的分析 — 持久存储在Bun本地SQLite存储中，并在其自己的端口上提供服务：
```bash
mikrotik-mcp serve --dashboard # → http://127.0.0.1:9090
```
请参阅 **[文档/可观察性.md](docs/observability.md)**。
## 模式
`schemas/` 提供了机器可读的JSON模式，**从TypeScript源代码生成** （`bun run gen:schemas`），因此它们永远不会漂移：
- `schemas/tool-catalog.json` — 所有640种工具，具有风险，描述和输入模式
- `schemas/tools/<name>.json` — 每个工具的输入模式
- `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) | 事务更改 |
| **[VPN指南](docs/vpn-guide.md)** | 每种隧道类型 + 如何构建它 |
| [提示](docs/prompts.md) | 9种引导工作流 |
| [架构](docs/architecture.md) | 它是如何构建的 |
| [安全](docs/security.md) | 凭证，风险门控 |
| [工具参考](docs/tools-reference.md) | 所有640种工具 |
| [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/
```
请参阅 **[文档/开发.md](docs/development.md)** 和 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 安全
使用您提供的凭证与RouterOS通过SSH进行对话；不会将任何内容发送到其他地方。工具值被引用/转义以防止控制台命令注入。破坏性和危险的工具被注解，以便客户端可以要求确认，并且在容器中输入纯密码的警告促使您使用密钥文件或秘密。详情： **[文档/安全.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>
连接信息
猜你喜欢
暂无推荐服务器