mikrotik-mcp-server

v1.0.14

Published

a month ago

MCP 服务器用于通过 AI 操作 MikroTik RouterOS

0High
0Medium
0Low

a923946240

mcp mikrotik routeros mcp-server

MikroTik RouterOS MCP 服务器

通过 Model Context Protocol (MCP) 让 AI 助手操作 MikroTik RouterOS 设备。

功能特性

✅ 执行 RouterOS 命令（add, print, set, remove 等操作）
✅ 支持两种连接方式：
- RouterOS API（默认，端口 8728）- 快速、高效
- SSH（端口 22）- 兼容性好，支持密钥认证
✅ 自动生成 67+ 个核心工具，包括：
- 接口管理（interface, bridge, port）
- IP 配置（address, route, neighbor）
- 防火墙（filter, nat）
- 证书管理（certificate）
- 用户管理（user）
- 系统管理（system, log）
✅ 自动连接管理和重连
✅ IDE 兼容性：完全兼容 Cursor、JetBrains IDE、CodeFlicker 等主流 IDE
✅ MCP 标准兼容：符合 MCP 2024-11-05 协议标准

安装

npm install
npm run build

配置

通过环境变量配置 RouterOS 连接信息：

使用 API 连接（推荐，默认）：

export ROUTEROS_HOST=192.168.88.1
export ROUTEROS_USER=admin
export ROUTEROS_PASSWORD=your_password
export ROUTEROS_PORT=8728          # API 端口，默认 8728
export ROUTEROS_SECURE=false       # 是否使用加密，默认 false
export ROUTEROS_CONNECTION_TYPE=api  # 连接类型，默认 api

使用 SSH 连接：

export ROUTEROS_HOST=192.168.88.1
export ROUTEROS_USER=admin
export ROUTEROS_PASSWORD=your_password
export ROUTEROS_PORT=22            # SSH 端口，默认 22
export ROUTEROS_CONNECTION_TYPE=ssh # 连接类型：ssh
# 可选：使用密钥认证
export ROUTEROS_PRIVATE_KEY=/path/to/private/key
export ROUTEROS_PASSPHRASE=key_passphrase

使用方法

作为 MCP 服务器运行

npm start

通过 npx 使用

npx mikrotik-mcp-server

在 Cursor 中配置

在 Cursor 的 MCP 设置文件（通常在 ~/.cursor/mcp.json 或项目配置中）添加：

{
  "mcpServers": {
    "mikrotik": {
      "command": "npx",
      "args": ["-y", "mikrotik-mcp-server"],
      "env": {
        "ROUTEROS_HOST": "192.168.88.1",
        "ROUTEROS_USER": "admin",
        "ROUTEROS_PASSWORD": "your_password",
        "ROUTEROS_PORT": "8728",
        "ROUTEROS_CONNECTION_TYPE": "api"
        // 或使用 SSH：
        // "ROUTEROS_PORT": "22",
        // "ROUTEROS_CONNECTION_TYPE": "ssh"
      }
    }
  }
}

重要提示：

工具名称格式为 mt_<命令路径>_<操作>（新格式），例如：mt_interface_print
也支持旧格式 mikrotik_<命令路径>_<操作>（向后兼容）
如果遇到工具名称包含服务器前缀（如 mikrotik-mcp-server-mt_xxx），服务器会自动处理
确保 MikroTik 设备的 API 服务已启用（默认端口 8728）

在其他 IDE 中配置

本服务器兼容多种 IDE，详细配置请参考 IDE 兼容性指南：

Cursor - 完全支持（自动/手动配置）
JetBrains IDE - IntelliJ IDEA, WebStorm, PyCharm 等（2025.2+）
CodeFlicker IDE - 完全支持
其他支持 MCP 的 IDE - 遵循标准 MCP 协议

可用工具

系统会根据命令文件自动生成对应的工具。每个 RouterOS 命令都会生成一个对应的 MCP 工具。

工具命名规则：mt_<命令路径>_<操作>（新格式）或 mikrotik_<命令路径>_<操作>（旧格式，向后兼容）

核心工具示例

接口管理：

mt_interface_print - 查看所有网络接口
mt_interface_bridge_print - 查看桥接接口
mt_interface_bridge_port_print - 查看桥接端口
mt_interface_bridge_add - 添加桥接接口
mt_interface_bridge_set - 修改桥接接口（需要 numbers 参数）
mt_interface_bridge_remove - 删除桥接接口（需要 numbers 参数）

IP 配置：

mt_ip_address_print - 查看 IP 地址
mt_ip_address_add - 添加 IP 地址
mt_ip_address_set - 修改 IP 地址（需要 numbers 参数）
mt_ip_address_remove - 删除 IP 地址（需要 numbers 参数）
mt_ip_route_print - 查看路由表
mt_ip_route_add - 添加路由
mt_ip_neighbor_print - 查看邻居发现表
mt_ip_dhcpclient_print - 查看 DHCP 客户端

防火墙：

mt_ip_firewall_filter_print - 查看防火墙过滤规则
mt_ip_firewall_filter_add - 添加防火墙规则
mt_ip_firewall_nat_print - 查看 NAT 规则
mt_ip_firewall_nat_add - 添加 NAT 规则

其他：

mt_certificate_print - 查看证书列表
mt_certificate_add - 添加证书
mt_user_print - 查看用户列表
mt_user_add - 添加用户
mt_file_print - 查看文件列表
mt_list_tools - 列出所有可用工具（帮助工具）

工具参数

每个工具的参数根据命令文件中的示例自动生成。例如：

mt_interface_bridge_add 工具参数：

name - 桥接名称
comment - 注释
等等...

mt_interface_bridge_set 工具参数：

numbers - 必需：要修改的项目 ID（从 print 结果中获取）
name - 桥接名称（可选）
comment - 注释（可选）
等等...

mt_interface_print 工具：

无参数（直接执行 /interface print）

使用示例

查看网络接口

使用 mt_interface_print 工具（无需参数）

查看证书列表

使用 mt_certificate_print 工具（无需参数）

添加桥接接口

使用 mt_interface_bridge_add 工具：
- name: "bridge1"

修改配置（set 操作）

使用 set 操作修改现有配置，需要指定要修改的项目 ID（numbers 参数）：

1. 首先使用 print 操作查看项目列表，获取项目 ID
2. 然后使用 set 操作修改，例如：
   - 工具: mt_interface_bridge_set
   - 参数:
     - numbers: "0"  // 要修改的项目 ID（从 print 结果中获取）
     - name: "bridge2"  // 要修改的属性

删除配置（remove 操作）

使用 remove 操作删除配置，需要指定要删除的项目 ID：

1. 首先使用 print 操作查看项目列表，获取项目 ID
2. 然后使用 remove 操作删除，例如：
   - 工具: mt_interface_bridge_remove
   - 参数:
     - numbers: "0"  // 要删除的项目 ID（从 print 结果中获取）

查看 IP 地址

使用 mt_ip_address_print 工具（无需参数）

查看完整的网络结构

使用以下工具组合查看完整的网络结构：

接口信息：mt_interface_print
IP 地址：mt_ip_address_print
路由表：mt_ip_route_print
邻居发现：mt_ip_neighbor_print
ARP 表：mt_ip_arp_print
桥接信息：mt_interface_bridge_print
桥接端口：mt_interface_bridge_port_print
防火墙规则：mt_ip_firewall_filter_print

列出所有可用工具

使用帮助工具查看所有可用工具：

工具名称: mt_list_tools
参数: {} 或 {"category": "ip"}  // category 可选值: interface, ip, firewall, system, certificate, user, log, all

开发

# 开发模式
npm run dev

# 构建
npm run build

故障排除

工具未显示

检查环境变量是否正确设置
重启 Cursor 以重新加载 MCP 服务器
查看控制台日志，应该看到 "已加载 X 个 RouterOS 工具"

工具调用失败

工具名称错误：确保使用正确的工具名称格式 mt_<路径>_<操作>（新格式）或 mikrotik_<路径>_<操作>（旧格式）
连接失败：检查 RouterOS 设备是否可访问，API 服务是否启用
权限不足：确保用户账户有足够权限执行操作
修改操作失败：
- 确保提供了正确的 numbers 参数（项目 ID）
- 使用 print 操作先查看项目列表，获取正确的 ID
- 检查参数格式是否正确（数字或逗号分隔的数字列表）

常见错误

Server not found: 检查 MCP 配置中的服务器名称
未知工具: 查看可用工具列表，使用正确的工具名称
连接失败: 检查网络连接和 API 端口（默认 8728）

连接方式选择

API 连接（推荐）

优点: 速度快、效率高、专为 RouterOS 设计
端口: 8728（非加密）或 8729（加密）
要求: 需要在 RouterOS 中启用 API 服务
配置: ROUTEROS_CONNECTION_TYPE=api

SSH 连接

优点: 兼容性好、支持密钥认证、更安全
端口: 22（默认）
要求: 需要在 RouterOS 中启用 SSH 服务
配置: ROUTEROS_CONNECTION_TYPE=ssh
密钥认证: 可设置 ROUTEROS_PRIVATE_KEY 和 ROUTEROS_PASSPHRASE

注意事项

安全性: 确保 RouterOS 密码安全，不要将密码提交到版本控制
权限: 确保使用的用户账户有足够的权限执行所需操作
连接: 确保网络可以访问 RouterOS 设备
服务启用:
- API 连接：确保 API 服务已启用（/ip service enable api）
- SSH 连接：确保 SSH 服务已启用（/ip service enable ssh）
端口:
- API: 默认 8728（非加密）或 8729（加密）
- SSH: 默认 22
工具数量: 当前版本包含 68 个核心工具，涵盖最常用的操作

支持的 RouterOS 命令类别

/certificate - 证书管理
/file - 文件管理
/interface - 接口管理
/ip - IP 配置
/ppp - PPP 连接
/queue - 队列管理
/system - 系统管理
/tool - 系统工具
/user - 用户管理
以及更多...

许可证

MIT