@usex/mikrotik-mcp 2.3.0 → 2.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +88 -62
- package/dist/cli.js +4293 -2094
- package/dist/index.d.ts +0 -4
- package/dist/index.js +3758 -2075
- package/dist/ui/dashboard.html +1 -1
- package/dist/ui/firewall-audit.html +20 -0
- package/dist/ui/firewall.html +1 -1
- package/dist/ui/interfaces.html +1 -1
- package/dist/ui/observability.html +11 -7
- package/dist/ui/records.html +1 -1
- package/package.json +4 -2
- package/schemas/README.md +5 -5
- package/schemas/tool-catalog.json +465 -4
- package/schemas/tools/apply_plan.json +23 -0
- package/schemas/tools/capture_config_snapshot.json +30 -0
- package/schemas/tools/diff_config_snapshots.json +31 -0
- package/schemas/tools/firewall_audit.json +19 -0
- package/schemas/tools/get_config_snapshot.json +16 -0
- package/schemas/tools/get_neighbor_discovery_settings.json +7 -0
- package/schemas/tools/list_config_snapshots.json +15 -0
- package/schemas/tools/list_neighbors.json +24 -0
- package/schemas/tools/mirror_traffic_to_capture.json +36 -0
- package/schemas/tools/packet_capture_status.json +16 -0
- package/schemas/tools/plan_changes.json +19 -0
- package/schemas/tools/remove_config_snapshot.json +16 -0
- package/schemas/tools/set_neighbor_discovery_settings.json +25 -0
- package/schemas/tools/start_packet_capture.json +31 -0
- package/schemas/tools/stop_packet_capture.json +7 -0
package/README.md
CHANGED
|
@@ -33,16 +33,16 @@ in memory and auto-reverts if your session drops, so you can't lock yourself out
|
|
|
33
33
|
"env": {
|
|
34
34
|
"MIKROTIK_HOST": "192.168.88.1",
|
|
35
35
|
"MIKROTIK_USERNAME": "admin",
|
|
36
|
-
"MIKROTIK_PASSWORD": "your-password"
|
|
37
|
-
}
|
|
38
|
-
}
|
|
39
|
-
}
|
|
36
|
+
"MIKROTIK_PASSWORD": "your-password",
|
|
37
|
+
},
|
|
38
|
+
},
|
|
39
|
+
},
|
|
40
40
|
}
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
-
>
|
|
44
|
-
>
|
|
45
|
-
>
|
|
43
|
+
> _"Show me the firewall input chain, then block SSH from the WAN under safe mode."_
|
|
44
|
+
> _"Build an IKEv2 site-to-site tunnel to 203.0.113.5 for 192.168.20.0/24."_
|
|
45
|
+
> _"Why can't VLAN 50 reach the internet?"_
|
|
46
46
|
|
|
47
47
|
## Why it's different
|
|
48
48
|
|
|
@@ -118,29 +118,29 @@ bun run build # bundle to dist/
|
|
|
118
118
|
**640 tools across 51 modules.** Full, always-current reference (parameters +
|
|
119
119
|
risk per tool) is generated from source: **[docs/tools-reference.md](docs/tools-reference.md)**.
|
|
120
120
|
|
|
121
|
-
| Group
|
|
122
|
-
|
|
123
|
-
| **Interfaces**
|
|
124
|
-
| **Addressing & Routing** |
|
|
125
|
-
| **Dynamic Routing**
|
|
126
|
-
| **Security**
|
|
127
|
-
| **VPN & Tunneling**
|
|
128
|
-
| **QoS**
|
|
129
|
-
| **System & Ops**
|
|
121
|
+
| Group | Tools | Modules |
|
|
122
|
+
| ------------------------ | ----: | ---------------------------------------------------------------------------------------------------------- |
|
|
123
|
+
| **Interfaces** | 41 | interfaces, VLAN, bridge, wireless, PoE |
|
|
124
|
+
| **Addressing & Routing** | 46 | IP addresses, IP pools, routing, DHCP, DNS |
|
|
125
|
+
| **Dynamic Routing** | 99 | router-id, settings, tables, rules, next-hops, filters, BFD, BGP, OSPF, RIP, PIM-SM, IGMP proxy, GMP, RPKI |
|
|
126
|
+
| **Security** | 34 | firewall filter, NAT, address-lists, certificates, IP services |
|
|
127
|
+
| **VPN & Tunneling** | 96 | WireGuard, IPsec, PPP, L2TP, PPTP, SSTP, OpenVPN, GRE/IPIP/EoIP/VXLAN |
|
|
128
|
+
| **QoS** | 19 | queue types, queue trees, simple queues |
|
|
129
|
+
| **System & Ops** | 102 | system, network tools, scheduler/scripts, users, logs, backup, Safe Mode |
|
|
130
130
|
|
|
131
131
|
## VPN & tunneling — expert coverage
|
|
132
132
|
|
|
133
133
|
Every MikroTik VPN technology, modeled the way RouterOS actually layers them (the
|
|
134
134
|
PPP-based VPNs share one `/ppp` backend for users and addressing):
|
|
135
135
|
|
|
136
|
-
| Need
|
|
137
|
-
|
|
138
|
-
| MikroTik ↔ MikroTik, modern clients | **WireGuard**
|
|
139
|
-
| Interop site-to-site / native IKEv2 | **IPsec**
|
|
140
|
-
| Built-in OS VPN clients
|
|
141
|
-
| Through restrictive firewalls
|
|
142
|
-
| Cross-platform OpenVPN
|
|
143
|
-
| Route / L2-bridge between sites
|
|
136
|
+
| Need | Use | Build it with |
|
|
137
|
+
| ----------------------------------- | ----------------------- | -------------------------------------------------------------------------------------- |
|
|
138
|
+
| MikroTik ↔ MikroTik, modern clients | **WireGuard** | `create_wireguard_interface`, `add_wireguard_peer`, `generate_wireguard_client_config` |
|
|
139
|
+
| Interop site-to-site / native IKEv2 | **IPsec** | `create_ipsec_{profile,peer,identity,proposal,policy}`, `get_ipsec_active_peers` |
|
|
140
|
+
| Built-in OS VPN clients | **L2TP/IPsec** | `set_l2tp_server`, `create_ppp_secret`, `create_ppp_profile` |
|
|
141
|
+
| Through restrictive firewalls | **SSTP** (TLS) | `set_sstp_server`, `create_sstp_client` |
|
|
142
|
+
| Cross-platform OpenVPN | **OpenVPN** | `set_ovpn_server`, `create_ovpn_client` |
|
|
143
|
+
| Route / L2-bridge between sites | **GRE/IPIP/EoIP/VXLAN** | `create_gre_tunnel`, `create_eoip_tunnel`, `create_vxlan_tunnel` |
|
|
144
144
|
|
|
145
145
|
Not sure which? Invoke the **`choose-vpn-solution`** prompt and the server
|
|
146
146
|
recommends one and outlines the build. Details: **[docs/vpn-guide.md](docs/vpn-guide.md)**.
|
|
@@ -157,8 +157,8 @@ both ends**. Point the server at a JSON file (or `MIKROTIK_DEVICES`):
|
|
|
157
157
|
"defaultDevice": "site-a",
|
|
158
158
|
"devices": {
|
|
159
159
|
"site-a": { "host": "203.0.113.10", "username": "admin", "keyFilename": "/keys/site-a" },
|
|
160
|
-
"site-b": { "host": "198.51.100.20", "username": "admin", "password": "••••" }
|
|
161
|
-
}
|
|
160
|
+
"site-b": { "host": "198.51.100.20", "username": "admin", "password": "••••" },
|
|
161
|
+
},
|
|
162
162
|
}
|
|
163
163
|
```
|
|
164
164
|
|
|
@@ -193,11 +193,11 @@ See **[docs/prompts.md](docs/prompts.md)**.
|
|
|
193
193
|
|
|
194
194
|
## Transports
|
|
195
195
|
|
|
196
|
-
| Transport
|
|
197
|
-
|
|
198
|
-
| **stdio** (default) | Claude Desktop, local MCP clients | `mikrotik-mcp serve`
|
|
199
|
-
| **streamable-http** | Remote / shared, behind a proxy
|
|
200
|
-
| **sse**
|
|
196
|
+
| Transport | When | Run |
|
|
197
|
+
| ------------------- | --------------------------------- | ---------------------------------------------------------------- |
|
|
198
|
+
| **stdio** (default) | Claude Desktop, local MCP clients | `mikrotik-mcp serve` |
|
|
199
|
+
| **streamable-http** | Remote / shared, behind a proxy | `mikrotik-mcp serve --transport streamable-http --mcp-port 8000` |
|
|
200
|
+
| **sse** | Legacy HTTP clients | `mikrotik-mcp serve --transport sse` |
|
|
201
201
|
|
|
202
202
|
HTTP transports expose `POST /mcp` and a `GET /health` check, with DNS-rebinding
|
|
203
203
|
protection that reconciles with your bind host automatically. See
|
|
@@ -220,20 +220,20 @@ See **[docs/safe-mode.md](docs/safe-mode.md)**.
|
|
|
220
220
|
Connection and transport settings come from `MIKROTIK_*` env vars or matching CLI
|
|
221
221
|
flags (highest precedence last: defaults → env → flags).
|
|
222
222
|
|
|
223
|
-
| Variable
|
|
224
|
-
|
|
225
|
-
| `MIKROTIK_HOST`
|
|
226
|
-
| `MIKROTIK_USERNAME`
|
|
227
|
-
| `MIKROTIK_PORT`
|
|
228
|
-
| `MIKROTIK_PASSWORD`
|
|
229
|
-
| `MIKROTIK_KEY_FILENAME`
|
|
230
|
-
| `MIKROTIK_PRIVATE_KEY`
|
|
231
|
-
| `MIKROTIK_KEY_PASSPHRASE`
|
|
232
|
-
| `MIKROTIK_CONFIG_FILE`
|
|
233
|
-
| `MIKROTIK_DEVICES`
|
|
234
|
-
| `MIKROTIK_MCP__TRANSPORT`
|
|
235
|
-
| `MIKROTIK_MCP__PORT`
|
|
236
|
-
| `MIKROTIK_DASHBOARD__ENABLED` | `--dashboard`
|
|
223
|
+
| Variable | Flag | Default | Purpose |
|
|
224
|
+
| ----------------------------- | ------------------ | ----------- | ----------------------------------------------------------------- |
|
|
225
|
+
| `MIKROTIK_HOST` | `--host` | `127.0.0.1` | RouterOS host |
|
|
226
|
+
| `MIKROTIK_USERNAME` | `--username` | `admin` | SSH user |
|
|
227
|
+
| `MIKROTIK_PORT` | `--port` | `22` | SSH port |
|
|
228
|
+
| `MIKROTIK_PASSWORD` | `--password` | — | SSH password _(or use a key →)_ |
|
|
229
|
+
| `MIKROTIK_KEY_FILENAME` | `--key-filename` | — | SSH private-key file path |
|
|
230
|
+
| `MIKROTIK_PRIVATE_KEY` | `--private-key` | — | Inline private key (PEM) |
|
|
231
|
+
| `MIKROTIK_KEY_PASSPHRASE` | `--key-passphrase` | — | Passphrase for an encrypted key |
|
|
232
|
+
| `MIKROTIK_CONFIG_FILE` | `--config` | — | JSON file of named devices ([multi-device](docs/multi-device.md)) |
|
|
233
|
+
| `MIKROTIK_DEVICES` | `--devices` | — | Inline JSON of named devices |
|
|
234
|
+
| `MIKROTIK_MCP__TRANSPORT` | `--transport` | `stdio` | `stdio` / `streamable-http` / `sse` |
|
|
235
|
+
| `MIKROTIK_MCP__PORT` | `--mcp-port` | `8000` | HTTP bind port |
|
|
236
|
+
| `MIKROTIK_DASHBOARD__ENABLED` | `--dashboard` | `false` | Real-time observability dashboard ([docs](docs/observability.md)) |
|
|
237
237
|
|
|
238
238
|
Full table (incl. HTTP host, allow-lists, timeouts, `MIKROTIK_LOG_LEVEL`):
|
|
239
239
|
**[docs/configuration.md](docs/configuration.md)**.
|
|
@@ -251,33 +251,59 @@ mikrotik-mcp serve --dashboard # → http://127.0.0.1:9090
|
|
|
251
251
|
|
|
252
252
|
See **[docs/observability.md](docs/observability.md)**.
|
|
253
253
|
|
|
254
|
+
## Beyond the catalog
|
|
255
|
+
|
|
256
|
+
On top of the per-scope tools, the server ships higher-level workflows:
|
|
257
|
+
|
|
258
|
+
- **[Change Plan & Dry-Run](docs/change-plan.md)** — preview intended commands as
|
|
259
|
+
a terraform-style plan (risk-scored, lock-out-aware, safely reordered), then
|
|
260
|
+
`apply_plan` runs them under Safe Mode, shows the **exact `/export` diff**, and
|
|
261
|
+
commits only if the device is still reachable (auto-reverts a lock-out).
|
|
262
|
+
- **[Config Snapshots](docs/config-snapshots.md)** — store `/export` snapshots on
|
|
263
|
+
the host and **time-travel diff** any two, or one against the live device.
|
|
264
|
+
- **[Firewall Audit](docs/firewall-audit.md)** — `firewall_audit` finds shadowed,
|
|
265
|
+
overly-broad, missing-default-drop, duplicate and dead rules, risk-scored, with
|
|
266
|
+
one-click fixes in MCP App hosts.
|
|
267
|
+
- **[Packet Capture Studio](docs/packet-capture.md)** — stream mirrored packets to
|
|
268
|
+
the host as TZSP, decode them live in the dashboard, and export `.pcap`.
|
|
269
|
+
- **[Discovery](docs/discovery.md)** — `bun run discover` lists MikroTik devices on
|
|
270
|
+
the LAN by MAC (MNDP); the dashboard draws a live **topology map**.
|
|
271
|
+
- **[Config Studio](docs/config-studio.md)** — edit the config JSON in the
|
|
272
|
+
dashboard with autocomplete, validation, and safe-apply auto-rollback.
|
|
273
|
+
|
|
254
274
|
## Schemas
|
|
255
275
|
|
|
256
276
|
`schemas/` ships machine-readable JSON Schemas, **generated from the TypeScript
|
|
257
277
|
source** (`bun run gen:schemas`) so they can never drift:
|
|
258
278
|
|
|
259
|
-
- `schemas/tool-catalog.json` —
|
|
279
|
+
- `schemas/tool-catalog.json` — every tool with risk, description, and input schema
|
|
260
280
|
- `schemas/tools/<name>.json` — per-tool input schema
|
|
261
281
|
- `schemas/config.schema.json` — the runtime configuration
|
|
262
282
|
|
|
263
283
|
## Documentation
|
|
264
284
|
|
|
265
|
-
| Doc
|
|
266
|
-
|
|
267
|
-
| [Getting started](docs/getting-started.md)
|
|
268
|
-
| [Configuration](docs/configuration.md)
|
|
269
|
-
| [Multiple devices](docs/multi-device.md)
|
|
270
|
-
| [Connecting clients](docs/connecting-clients.md)
|
|
271
|
-
| [Transports](docs/transports.md)
|
|
272
|
-
| **[Observability](docs/observability.md)**
|
|
273
|
-
| [Safe Mode](docs/safe-mode.md)
|
|
274
|
-
| **[
|
|
275
|
-
| [
|
|
276
|
-
| [
|
|
277
|
-
| [
|
|
278
|
-
| [
|
|
279
|
-
| [
|
|
280
|
-
| [
|
|
285
|
+
| Doc | |
|
|
286
|
+
| ------------------------------------------------------------- | ----------------------------------------------------------- |
|
|
287
|
+
| [Getting started](docs/getting-started.md) | Install, verify, first run |
|
|
288
|
+
| [Configuration](docs/configuration.md) | Every env var & flag |
|
|
289
|
+
| [Multiple devices](docs/multi-device.md) | Manage several routers; per-call targeting |
|
|
290
|
+
| [Connecting clients](docs/connecting-clients.md) | Claude Desktop, stdio, HTTP |
|
|
291
|
+
| [Transports](docs/transports.md) | stdio / HTTP / SSE, DNS-rebinding |
|
|
292
|
+
| **[Observability](docs/observability.md)** | Real-time dashboard: live feed + analytics, SQLite |
|
|
293
|
+
| [Safe Mode](docs/safe-mode.md) | Transactional changes |
|
|
294
|
+
| **[Change Plan & Dry-Run](docs/change-plan.md)** | Preview commands, apply with the exact diff + auto-rollback |
|
|
295
|
+
| **[Config Snapshots](docs/config-snapshots.md)** | `/export` snapshots + time-travel diff |
|
|
296
|
+
| **[Firewall Audit](docs/firewall-audit.md)** | Shadowed/broad/dead rules, risk-scored |
|
|
297
|
+
| **[Packet Capture Studio](docs/packet-capture.md)** | Live TZSP capture + pcap export |
|
|
298
|
+
| **[Discovery](docs/discovery.md)** | `bun run discover`, MNDP neighbours, topology map |
|
|
299
|
+
| **[Config Studio](docs/config-studio.md)** | Edit config in the dashboard with autocomplete |
|
|
300
|
+
| **[VPN guide](docs/vpn-guide.md)** | Every tunnel type + how to build it |
|
|
301
|
+
| [Prompts](docs/prompts.md) | The 9 guided workflows |
|
|
302
|
+
| [Architecture](docs/architecture.md) | How it's built |
|
|
303
|
+
| [Security](docs/security.md) | Credentials, risk gating |
|
|
304
|
+
| [Tool reference](docs/tools-reference.md) | The full generated catalog |
|
|
305
|
+
| [MCP Inspector](docs/inspector.md) | Test tools/prompts in the UI or CLI |
|
|
306
|
+
| [Development](docs/development.md) · [Docker](docs/docker.md) | Build, test, deploy |
|
|
281
307
|
|
|
282
308
|
## Development
|
|
283
309
|
|