mikromcp 1.0.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/LICENSE +21 -0
- package/README.md +510 -0
- package/config/identities.example.yaml +42 -0
- package/config/routers.example.yaml +68 -0
- package/dist/main.js +9532 -0
- package/package.json +76 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ali Karami
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,510 @@
|
|
|
1
|
+
# MikroMCP
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<picture>
|
|
5
|
+
<source media="(prefers-color-scheme: dark)" srcset="./docs/assets/MikroMCP-logo-dark.png">
|
|
6
|
+
<source media="(prefers-color-scheme: light)" srcset="./docs/assets/MikroMCP-logo-light.png">
|
|
7
|
+
<img alt="MikroMCP" src="./docs/assets/MikroMCP-logo-dark.png" width="700">
|
|
8
|
+
</picture>
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
> **AI-native network automation for MikroTik RouterOS.** MikroMCP exposes RouterOS as a typed, auditable [Model Context Protocol](https://modelcontextprotocol.io) server so Claude, Cursor, Codex, and other MCP clients can inspect, diagnose, and safely operate MikroTik routers in natural language.
|
|
12
|
+
|
|
13
|
+
[](https://github.com/AliKarami/MikroMCP/actions/workflows/ci.yml)
|
|
14
|
+
[](https://github.com/AliKarami/MikroMCP/actions/workflows/release.yml)
|
|
15
|
+
[](package.json)
|
|
16
|
+
[](LICENSE)
|
|
17
|
+
[](package.json)
|
|
18
|
+
[](https://help.mikrotik.com/docs/display/ROS/REST+API)
|
|
19
|
+
[](https://modelcontextprotocol.io)
|
|
20
|
+
[](#available-tools)
|
|
21
|
+
|
|
22
|
+
MikroMCP exists because raw router CLI access is the wrong abstraction for AI agents. RouterOS is powerful, but asking an LLM to improvise shell commands against production network gear is risky. MikroMCP gives agents a controlled tool surface: strict schemas, idempotent writes, dry-run previews, per-router circuit breakers, retry policies, RBAC, audit logs, snapshots, and rollback-aware change workflows.
|
|
23
|
+
|
|
24
|
+
**In one sentence:** MikroMCP turns MikroTik RouterOS into a production-minded MCP control plane for AI infrastructure, DevOps automation, and modern router management.
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Why It Matters
|
|
31
|
+
|
|
32
|
+
| Instead of... | MikroMCP gives you... |
|
|
33
|
+
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
34
|
+
| Hand-written RouterOS CLI snippets from chat | Typed MCP tools with strict Zod validation |
|
|
35
|
+
| Blind config changes | Dry-run previews, idempotency checks, snapshots, and rollback tooling |
|
|
36
|
+
| One-off scripts per router | A multi-router registry with per-router credentials, tags, TLS, SSH, and maintenance windows |
|
|
37
|
+
| Raw network access for every assistant | RBAC identities, bearer tokens for HTTP mode, tool allowlists, and audit trails |
|
|
38
|
+
| Fragile troubleshooting workflows | Router-originated ping, traceroute, torch, logs, interfaces, DHCP, firewall, routes, WiFi, WireGuard, and more |
|
|
39
|
+
|
|
40
|
+
MikroMCP is especially useful when you want AI agents to help with network operations without giving them unchecked terminal access.
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Feature Showcase
|
|
45
|
+
|
|
46
|
+
| Category | What MikroMCP covers |
|
|
47
|
+
| -------------------------- | ----------------------------------------------------------------------------------------------------- |
|
|
48
|
+
| ๐งญ **Router management** | System status, clock, reboot, packages, files, scripts, scheduler jobs, containers |
|
|
49
|
+
| ๐ **Network operations** | Interfaces, VLANs, IP addresses, DHCP leases, DNS static records, bridge ports, WiFi clients |
|
|
50
|
+
| ๐ฅ **Firewall and policy** | Filter/NAT rules, mangle rules, address lists, route tables, routing rules |
|
|
51
|
+
| ๐ฐ๏ธ **Routing visibility** | Static routes, routing tables, BGP peers, OSPF neighbors |
|
|
52
|
+
| ๐ **Secure access** | HTTP bearer auth, bcrypt token hashes, RBAC, router/tool restrictions, confirmation tokens |
|
|
53
|
+
| ๐งช **Diagnostics** | Router-originated `ping`, `traceroute`, `torch`, log filtering, guarded SSH command execution |
|
|
54
|
+
| ๐ก๏ธ **Change safety** | Dry-run, idempotent writes, snapshots, write journal, `plan_changes`, `apply_plan`, `rollback_change` |
|
|
55
|
+
| โ๏ธ **Production behavior** | Retries for read tools, per-router circuit breakers, correlation IDs, structured logs, audit logs |
|
|
56
|
+
| ๐ค **AI-agent fit** | Human-readable responses plus structured JSON content for reasoning, chaining, and automation |
|
|
57
|
+
| ๐งฉ **MCP compatibility** | stdio for desktop clients, Streamable HTTP and legacy SSE for remote or service-style clients |
|
|
58
|
+
|
|
59
|
+
**Best-in-class strengths:** MikroMCP is not just a thin REST wrapper. It models operational safety around RouterOS: typed tool contracts, safe write patterns, router-aware credentials, destructive-action gates, and rollback-oriented workflows.
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## Demo
|
|
64
|
+
|
|
65
|
+
### Usage
|
|
66
|
+
|
|
67
|
+
<p align="center">
|
|
68
|
+
<img src="docs/assets/demo-1.gif" width="900" />
|
|
69
|
+
</p>
|
|
70
|
+
|
|
71
|
+
### MCP Inspector
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## Quick Start
|
|
78
|
+
|
|
79
|
+
### Prerequisites
|
|
80
|
+
|
|
81
|
+
- Node.js 22 or newer
|
|
82
|
+
- MikroTik RouterOS 7.x with the REST API enabled
|
|
83
|
+
- A RouterOS user with the policies required by the tools you plan to use
|
|
84
|
+
- Git and npm
|
|
85
|
+
|
|
86
|
+
Recommended RouterOS policies for full tool coverage:
|
|
87
|
+
|
|
88
|
+
```text
|
|
89
|
+
read, write, api, rest-api, test, ssh, sniff, ftp
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Notes:
|
|
93
|
+
|
|
94
|
+
- `ssh` is required for `ping`, `traceroute`, `torch`, and `run_command`.
|
|
95
|
+
- `sniff` is required by `torch`.
|
|
96
|
+
- `ftp` is required only for `upload_file`.
|
|
97
|
+
|
|
98
|
+
### Install Locally
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
git clone https://github.com/AliKarami/MikroMCP.git
|
|
102
|
+
cd MikroMCP
|
|
103
|
+
npm install
|
|
104
|
+
npm run build
|
|
105
|
+
cp config/routers.example.yaml config/routers.yaml
|
|
106
|
+
cp config/identities.example.yaml config/identities.yaml
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Edit `config/routers.yaml`:
|
|
110
|
+
|
|
111
|
+
```yaml
|
|
112
|
+
routers:
|
|
113
|
+
core-01:
|
|
114
|
+
host: "10.0.0.1"
|
|
115
|
+
port: 443
|
|
116
|
+
tls:
|
|
117
|
+
enabled: true
|
|
118
|
+
rejectUnauthorized: true
|
|
119
|
+
credentials:
|
|
120
|
+
source: "env"
|
|
121
|
+
envPrefix: "ROUTER_CORE01"
|
|
122
|
+
tags: ["core", "production"]
|
|
123
|
+
rosVersion: "7.14"
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Provide router credentials through environment variables:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
export ROUTER_CORE01_USER="mcp-api"
|
|
130
|
+
export ROUTER_CORE01_PASS="your-router-password"
|
|
131
|
+
npm start
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### Docker
|
|
135
|
+
|
|
136
|
+
#### Pull and run
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
docker pull ghcr.io/alikarami/mikromcp:latest
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
One-liner with environment variables:
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
docker run --rm \
|
|
146
|
+
-e MIKROMCP_TRANSPORT=http \
|
|
147
|
+
-e MIKROMCP_PORT=3000 \
|
|
148
|
+
-e MIKROMCP_CONFIRMATION_SECRET="$(openssl rand -hex 32)" \
|
|
149
|
+
-e ROUTER_CORE01_USER=mcp-api \
|
|
150
|
+
-e ROUTER_CORE01_PASS=your-router-password \
|
|
151
|
+
-v "$(pwd)/config:/app/config:ro" \
|
|
152
|
+
-p 3000:3000 \
|
|
153
|
+
ghcr.io/alikarami/mikromcp:latest
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
#### Docker Compose
|
|
157
|
+
|
|
158
|
+
Copy the example file and fill in your `.env`:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
cp docker-compose.example.yml docker-compose.yml
|
|
162
|
+
cp config/routers.example.yaml config/routers.yaml
|
|
163
|
+
cp config/identities.example.yaml config/identities.yaml
|
|
164
|
+
# edit config/routers.yaml and set MIKROMCP_CONFIRMATION_SECRET + router credentials in .env
|
|
165
|
+
docker compose up -d
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
See `docker-compose.example.yml` for the full service definition.
|
|
169
|
+
|
|
170
|
+
#### Build from source
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
docker build -t mikromcp .
|
|
174
|
+
docker run --rm -e MIKROMCP_TRANSPORT=http -p 3000:3000 mikromcp
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## Connect An MCP Client
|
|
180
|
+
|
|
181
|
+
### Claude Desktop
|
|
182
|
+
|
|
183
|
+
Add MikroMCP to `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS:
|
|
184
|
+
|
|
185
|
+
```json
|
|
186
|
+
{
|
|
187
|
+
"mcpServers": {
|
|
188
|
+
"mikrotik": {
|
|
189
|
+
"command": "node",
|
|
190
|
+
"args": ["/absolute/path/to/MikroMCP/dist/main.js"],
|
|
191
|
+
"env": {
|
|
192
|
+
"MIKROMCP_CONFIG_PATH": "/absolute/path/to/MikroMCP/config/routers.yaml",
|
|
193
|
+
"ROUTER_CORE01_USER": "mcp-api",
|
|
194
|
+
"ROUTER_CORE01_PASS": "your-router-password"
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
Restart Claude Desktop, then ask:
|
|
202
|
+
|
|
203
|
+
```text
|
|
204
|
+
Use MikroMCP to show CPU, memory, uptime, active interfaces, and warning logs for core-01.
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
### HTTP / SSE Mode
|
|
208
|
+
|
|
209
|
+
HTTP mode is useful for service deployments and MCP clients that connect over a local or private network endpoint.
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
export MIKROMCP_TRANSPORT=http
|
|
213
|
+
export MIKROMCP_PORT=3000
|
|
214
|
+
export MIKROMCP_BIND_HOST=127.0.0.1
|
|
215
|
+
export MIKROMCP_CONFIRMATION_SECRET="$(openssl rand -hex 32)"
|
|
216
|
+
export ROUTER_CORE01_USER="mcp-api"
|
|
217
|
+
export ROUTER_CORE01_PASS="your-router-password"
|
|
218
|
+
npm start
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Every HTTP/SSE request must include:
|
|
222
|
+
|
|
223
|
+
```text
|
|
224
|
+
Authorization: Bearer <token>
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
Tokens are configured as bcrypt hashes in `config/identities.yaml`.
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## Configuration Reference
|
|
232
|
+
|
|
233
|
+
| Variable | Default | Purpose |
|
|
234
|
+
| --------------------------------- | ------------------------ | ------------------------------------------------------ |
|
|
235
|
+
| `MIKROMCP_TRANSPORT` | `stdio` | `stdio` or `http` |
|
|
236
|
+
| `MIKROMCP_CONFIG_PATH` | `config/routers.yaml` | Router registry path |
|
|
237
|
+
| `MIKROMCP_IDENTITIES_PATH` | `config/identities.yaml` | Identity and bearer-token registry |
|
|
238
|
+
| `MIKROMCP_STDIO_IDENTITY` | built-in superadmin | Named identity for stdio mode |
|
|
239
|
+
| `MIKROMCP_PORT` | `3000` | HTTP transport port |
|
|
240
|
+
| `MIKROMCP_BIND_HOST` | `127.0.0.1` | HTTP bind address |
|
|
241
|
+
| `MIKROMCP_CONFIRMATION_SECRET` | unset | HMAC secret for destructive-action confirmation tokens |
|
|
242
|
+
| `MIKROMCP_AUDIT_LOG_PATH` | unset | Optional NDJSON audit log file path |
|
|
243
|
+
| `MIKROMCP_HTTP_MAX_BODY_BYTES` | `1048576` | HTTP request body cap |
|
|
244
|
+
| `MIKROMCP_HTTP_RATE_LIMIT_RPM` | `60` | Requests per minute per IP; `0` disables rate limiting |
|
|
245
|
+
| `MIKROMCP_SSH_COMMAND_TIMEOUT_MS` | `30000` | SSH command timeout |
|
|
246
|
+
| `MIKROMCP_SSH_MAX_OUTPUT_BYTES` | `524288` | SSH output cap |
|
|
247
|
+
| `MIKROMCP_CMD_ALLOW` | unset | Global allowlist patterns for `run_command` |
|
|
248
|
+
| `MIKROMCP_CMD_DENY` | unset | Global denylist patterns for `run_command` |
|
|
249
|
+
| `ROUTER_<PREFIX>_USER` | unset | Router username from `envPrefix` |
|
|
250
|
+
| `ROUTER_<PREFIX>_PASS` | unset | Router password from `envPrefix` |
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## Available Tools
|
|
255
|
+
|
|
256
|
+
MikroMCP currently registers **77 MCP tools**.
|
|
257
|
+
|
|
258
|
+
| Area | Tools |
|
|
259
|
+
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
260
|
+
| System | `get_system_status`, `get_system_clock`, `set_system_clock`, `reboot` |
|
|
261
|
+
| Interfaces and IP | `list_interfaces`, `create_vlan`, `manage_ip_address` |
|
|
262
|
+
| DHCP and DNS | `list_dhcp_leases`, `list_dns_entries`, `manage_dns_entry`, `get_dns_settings` |
|
|
263
|
+
| DHCP Servers & Pools | `list_dhcp_servers`, `manage_dhcp_server`, `list_dhcp_pools`, `manage_dhcp_pool` |
|
|
264
|
+
| Routing | `list_routes`, `manage_route`, `list_routing_rules`, `manage_routing_rule`, `list_routing_tables`, `manage_routing_table` |
|
|
265
|
+
| Routing protocols | `list_bgp_peers`, `list_ospf_neighbors` |
|
|
266
|
+
| Firewall | `list_firewall_rules`, `manage_firewall_rule`, `list_mangle_rules`, `manage_mangle_rule`, `list_address_list_entries`, `manage_address_list_entry` |
|
|
267
|
+
| Bridge, WiFi, WireGuard | `list_bridges`, `manage_bridge`, `manage_bridge_port`, `list_wifi_interfaces`, `list_wifi_clients`, `manage_wifi_interface`, `list_wireguard_interfaces`, `list_wireguard_peers`, `manage_wireguard_peer` |
|
|
268
|
+
| IPSec/VPN | `list_ipsec_peers`, `list_ipsec_policies`, `manage_ipsec_peer` |
|
|
269
|
+
| Certificates | `list_certificates`, `manage_certificate` |
|
|
270
|
+
| Users | `list_users`, `manage_user` |
|
|
271
|
+
| Queues/QoS | `list_queues`, `manage_queue` |
|
|
272
|
+
| VRRP | `list_vrrp_instances`, `manage_vrrp_instance` |
|
|
273
|
+
| SNMP & NTP | `get_snmp_settings`, `get_ntp_settings` |
|
|
274
|
+
| Netwatch | `list_netwatch_entries`, `manage_netwatch_entry` |
|
|
275
|
+
| Discovery & ARP | `list_neighbors`, `list_arp_entries` |
|
|
276
|
+
| Diagnostics | `ping`, `traceroute`, `torch`, `get_log`, `run_command` |
|
|
277
|
+
| Automation | `list_scripts`, `manage_script`, `run_script`, `list_scheduled_jobs`, `manage_scheduled_job` |
|
|
278
|
+
| Runtime | `list_packages`, `manage_package`, `list_files`, `get_file_content`, `upload_file`, `list_containers`, `manage_container` |
|
|
279
|
+
| Change management | `plan_changes`, `apply_plan`, `rollback_change` |
|
|
280
|
+
| Fleet operations | `check_router_health`, `bulk_execute` |
|
|
281
|
+
|
|
282
|
+
```mermaid
|
|
283
|
+
mindmap
|
|
284
|
+
root((MikroMCP tools))
|
|
285
|
+
Operations
|
|
286
|
+
System status
|
|
287
|
+
Logs
|
|
288
|
+
Clock
|
|
289
|
+
Reboot
|
|
290
|
+
Network
|
|
291
|
+
Interfaces
|
|
292
|
+
VLANs
|
|
293
|
+
DHCP
|
|
294
|
+
DNS
|
|
295
|
+
WiFi
|
|
296
|
+
WireGuard
|
|
297
|
+
Policy
|
|
298
|
+
Firewall
|
|
299
|
+
NAT
|
|
300
|
+
Mangle
|
|
301
|
+
Address lists
|
|
302
|
+
Routing rules
|
|
303
|
+
Automation
|
|
304
|
+
Scripts
|
|
305
|
+
Scheduler
|
|
306
|
+
Files
|
|
307
|
+
Containers
|
|
308
|
+
Safety
|
|
309
|
+
Plan changes
|
|
310
|
+
Apply plan
|
|
311
|
+
Rollback change
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
---
|
|
315
|
+
|
|
316
|
+
## Real-World Usage Examples
|
|
317
|
+
|
|
318
|
+
### Router Inspection
|
|
319
|
+
|
|
320
|
+
```text
|
|
321
|
+
Use MikroMCP to inspect core-01. Summarize system resources, RouterOS version,
|
|
322
|
+
running interfaces, active routes, DNS settings, and recent warning/error logs.
|
|
323
|
+
Flag anything that looks operationally risky.
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
### Firewall Management
|
|
327
|
+
|
|
328
|
+
```text
|
|
329
|
+
List firewall filter and NAT rules on edge-01. Identify disabled rules,
|
|
330
|
+
overlapping port forwards, broad accept rules, and anything without comments.
|
|
331
|
+
Do not change anything yet.
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
### Safe Static Route Change
|
|
335
|
+
|
|
336
|
+
```text
|
|
337
|
+
Dry-run a route on core-01 for 10.20.0.0/16 via 192.168.88.1 in the main table.
|
|
338
|
+
Show the exact planned diff and tell me whether an existing route conflicts.
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
### WireGuard Operations
|
|
342
|
+
|
|
343
|
+
```text
|
|
344
|
+
Show WireGuard peers on branch-02. Sort by last handshake age and flag peers
|
|
345
|
+
that have not handshaken recently or have no transfer counters.
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
### Interface Diagnostics
|
|
349
|
+
|
|
350
|
+
```text
|
|
351
|
+
Check interface health on edge-01, then run ping and traceroute from the router
|
|
352
|
+
to 1.1.1.1. If packet loss is present, use torch on the WAN interface for a
|
|
353
|
+
short traffic snapshot.
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
### Configuration Backup And Audit
|
|
357
|
+
|
|
358
|
+
```text
|
|
359
|
+
List files, scripts, scheduled jobs, firewall rules, DNS static records, and
|
|
360
|
+
routes on core-01. Produce an audit summary with change-risk notes and suggested
|
|
361
|
+
cleanup tasks.
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
### Plan / Apply / Rollback Workflow
|
|
365
|
+
|
|
366
|
+
```text
|
|
367
|
+
Create a change plan that adds a DNS record and a firewall address-list entry
|
|
368
|
+
on edge-01. Use dry-run first, explain the plan, then wait for approval before
|
|
369
|
+
applying anything.
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
---
|
|
373
|
+
|
|
374
|
+
## Why MikroMCP Is Useful For AI Agents
|
|
375
|
+
|
|
376
|
+
MCP gives LLMs a standard way to call tools. MikroMCP makes RouterOS a high-quality MCP target by turning network operations into well-described, machine-readable, permission-aware actions.
|
|
377
|
+
|
|
378
|
+
AI assistants can use MikroMCP to:
|
|
379
|
+
|
|
380
|
+
- Investigate router state without memorizing RouterOS command syntax.
|
|
381
|
+
- Chain tool calls across interfaces, routes, firewall rules, logs, and diagnostics.
|
|
382
|
+
- Return both operator-friendly summaries and structured JSON for follow-up reasoning.
|
|
383
|
+
- Preview changes before mutation and explain exactly what would happen.
|
|
384
|
+
- Respect tool-level authorization, router scoping, maintenance windows, and confirmation gates.
|
|
385
|
+
|
|
386
|
+
This makes MikroMCP a practical bridge between MikroTik networks and the emerging AI infrastructure ecosystem: Claude MCP, LLM tooling, infrastructure automation, DevOps workflows, and network operations copilots.
|
|
387
|
+
|
|
388
|
+
---
|
|
389
|
+
|
|
390
|
+
## Documentation
|
|
391
|
+
|
|
392
|
+
| Resource | Use it for |
|
|
393
|
+
| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
|
|
394
|
+
| [ROADMAP.md](ROADMAP.md) | Shipped milestones and planned v1.0 work |
|
|
395
|
+
| [Architecture](https://github.com/AliKarami/MikroMCP/wiki/Architecture) | System layers and request pipeline |
|
|
396
|
+
| [Setup Guide](https://github.com/AliKarami/MikroMCP/wiki/Setup-Guide) | RouterOS REST setup and end-to-end onboarding |
|
|
397
|
+
| [Configuration](https://github.com/AliKarami/MikroMCP/wiki/Configuration) | Router registry, TLS, SSH, credentials, HTTP mode |
|
|
398
|
+
| [Running](https://github.com/AliKarami/MikroMCP/wiki/Running) | Local development and production commands |
|
|
399
|
+
| [Connecting to an MCP Client](https://github.com/AliKarami/MikroMCP/wiki/Connecting-to-an-MCP-Client) | Claude Desktop, Claude Code, Cursor, and other MCP clients |
|
|
400
|
+
| [Available Tools](https://github.com/AliKarami/MikroMCP/wiki/Available-Tools) | Tool parameters and example prompts |
|
|
401
|
+
| [Error Handling](https://github.com/AliKarami/MikroMCP/wiki/Error-Handling) | Typed errors, retry behavior, circuit breaker behavior |
|
|
402
|
+
| [Development](https://github.com/AliKarami/MikroMCP/wiki/Development) | Project structure, tests, MCP Inspector workflow |
|
|
403
|
+
| [Contributing](https://github.com/AliKarami/MikroMCP/wiki/Contributing) | Adding tools, coding conventions, PR checklist |
|
|
404
|
+
| [Roadmap](https://github.com/AliKarami/MikroMCP/wiki/Roadmap) | Wiki mirror of the milestone roadmap |
|
|
405
|
+
|
|
406
|
+
---
|
|
407
|
+
|
|
408
|
+
## Development
|
|
409
|
+
|
|
410
|
+
```bash
|
|
411
|
+
npm run dev # tsx watch hot-reload
|
|
412
|
+
npm run build # build ESM output to dist/main.js
|
|
413
|
+
npm start # run built server
|
|
414
|
+
npm test # run Vitest once
|
|
415
|
+
npm run typecheck # TypeScript type checking
|
|
416
|
+
npm run lint # ESLint
|
|
417
|
+
npm run format # Prettier
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
Run this before committing:
|
|
421
|
+
|
|
422
|
+
```bash
|
|
423
|
+
npm test
|
|
424
|
+
npm run typecheck
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
Key project paths:
|
|
428
|
+
|
|
429
|
+
| Path | Purpose |
|
|
430
|
+
| -------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
431
|
+
| `src/main.ts` | Loads config and starts stdio or HTTP transport |
|
|
432
|
+
| `src/mcp/tool-registry.ts` | Registers tools and applies auth, retry, circuit breaker, audit, snapshots, and credentials |
|
|
433
|
+
| `src/domain/tools/` | Tool definitions and handlers |
|
|
434
|
+
| `src/domain/snapshot/` | Snapshot, diff, and write-journal support |
|
|
435
|
+
| `src/adapter/rest-client.ts` | RouterOS REST API client |
|
|
436
|
+
| `src/adapter/ssh-client.ts` | SSH execution adapter for diagnostics and guarded commands |
|
|
437
|
+
| `src/config/router-registry.ts` | Router inventory loader |
|
|
438
|
+
| `config/routers.example.yaml` | Example multi-router registry |
|
|
439
|
+
| `config/identities.example.yaml` | Example RBAC identity registry |
|
|
440
|
+
|
|
441
|
+
---
|
|
442
|
+
|
|
443
|
+
## Roadmap
|
|
444
|
+
|
|
445
|
+
| Milestone | Status | Focus |
|
|
446
|
+
| --------- | ---------- | -------------------------------------------------------------------------------------------------------- |
|
|
447
|
+
| v0.1-v0.6 | โ
Shipped | Foundation, core tools, diagnostics, services, firewall, routing, automation, files, containers |
|
|
448
|
+
| v0.7 | โ
Shipped | Identity, bearer auth, RBAC, audit log, confirmation gate |
|
|
449
|
+
| v0.8 | โ
Shipped | Snapshots, write journal, plan/apply, rollback, maintenance windows |
|
|
450
|
+
| v0.9 | โ
Shipped | Fleet operations, IPSec, certificates, users, DHCP servers/pools, queues/QoS, VRRP, SNMP/NTP, Netwatch, discovery, ARP, health checks |
|
|
451
|
+
| v1.0 | ๐ Planned | Docker/npm/systemd distribution, Prometheus metrics, CHR integration tests, doctor CLI, stability policy |
|
|
452
|
+
|
|
453
|
+
See [ROADMAP.md](ROADMAP.md) for the complete milestone plan.
|
|
454
|
+
|
|
455
|
+
---
|
|
456
|
+
|
|
457
|
+
## Contributing
|
|
458
|
+
|
|
459
|
+
Issues, bug reports, tool requests, documentation improvements, and pull requests are welcome.
|
|
460
|
+
|
|
461
|
+
Good first contributions:
|
|
462
|
+
|
|
463
|
+
- Add a read-only tool for an uncovered RouterOS surface.
|
|
464
|
+
- Improve the wiki tool reference with examples and parameter tables.
|
|
465
|
+
- Add screenshots, demo GIFs, or topology diagrams.
|
|
466
|
+
- Expand tests around RouterOS response normalization and idempotency edge cases.
|
|
467
|
+
- Help validate RouterOS version compatibility across real MikroTik devices and CHR.
|
|
468
|
+
|
|
469
|
+
Development standards:
|
|
470
|
+
|
|
471
|
+
- TypeScript strict mode
|
|
472
|
+
- ESM imports with `.js` extensions
|
|
473
|
+
- Zod schemas with `.strict()`
|
|
474
|
+
- Idempotency and `dryRun` for write tools
|
|
475
|
+
- `MikroMCPError` for domain errors
|
|
476
|
+
- Focused Vitest coverage for every tool
|
|
477
|
+
|
|
478
|
+
Please open an issue before large changes so maintainers can align on scope.
|
|
479
|
+
|
|
480
|
+
---
|
|
481
|
+
|
|
482
|
+
## Security
|
|
483
|
+
|
|
484
|
+
MikroMCP is designed for sensitive infrastructure, but it still controls real network devices. Treat it like an operations system.
|
|
485
|
+
|
|
486
|
+
- Use least-privilege RouterOS users.
|
|
487
|
+
- Prefer TLS verification and certificate fingerprint pinning.
|
|
488
|
+
- Pin SSH host-key fingerprints for SSH-enabled tools.
|
|
489
|
+
- Keep router credentials in environment variables or a secrets system, not YAML.
|
|
490
|
+
- Use HTTP mode behind a trusted network boundary.
|
|
491
|
+
- Configure identities with the smallest practical `allowedRouters` and `allowedToolPatterns`.
|
|
492
|
+
- Enable audit logging for shared or production use.
|
|
493
|
+
- Test write tools with `dryRun: true` before applying changes.
|
|
494
|
+
|
|
495
|
+
For vulnerabilities or unsafe behavior, open a private security advisory if available, or contact the maintainer before publishing exploit details.
|
|
496
|
+
|
|
497
|
+
---
|
|
498
|
+
|
|
499
|
+
## Community And Support
|
|
500
|
+
|
|
501
|
+
- โญ Star the repository if MikroMCP helps your MikroTik or MCP workflow.
|
|
502
|
+
- ๐ด Fork it to add RouterOS surfaces your network depends on.
|
|
503
|
+
- ๐งต Open an issue for bugs, feature requests, compatibility notes, or documentation gaps.
|
|
504
|
+
- ๐ฃ๏ธ Follow the [roadmap](ROADMAP.md) for upcoming fleet, distribution, and production-readiness work.
|
|
505
|
+
|
|
506
|
+
---
|
|
507
|
+
|
|
508
|
+
## License
|
|
509
|
+
|
|
510
|
+
MikroMCP is released under the [MIT License](LICENSE).
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# MikroMCP Identity Configuration
|
|
2
|
+
#
|
|
3
|
+
# Each identity maps a bcrypt-hashed bearer token to an RBAC policy.
|
|
4
|
+
# Roles are semantic labels; enforcement is via allowedRouters and allowedToolPatterns.
|
|
5
|
+
#
|
|
6
|
+
# Token generation (two steps):
|
|
7
|
+
# 1. Generate raw token: openssl rand -hex 32
|
|
8
|
+
# 2. Hash it (bcrypt cost 12):
|
|
9
|
+
# node -e "const b=require('bcryptjs');b.hash(process.argv[1],12).then(console.log)" <raw-token>
|
|
10
|
+
#
|
|
11
|
+
# Store the raw token securely (password manager, secrets vault).
|
|
12
|
+
# Only the bcrypt hash goes in this file โ never the raw token.
|
|
13
|
+
#
|
|
14
|
+
# Roles: readonly | operator | admin | superadmin
|
|
15
|
+
# - readonly: Read-only tools. Requires confirmation for any destructive tool.
|
|
16
|
+
# - operator: Read + selected write tools. Requires confirmation for destructive tools.
|
|
17
|
+
# - admin: Full access. Skips confirmation gate.
|
|
18
|
+
# - superadmin: Full access. Same as admin but typically used for the built-in stdio identity.
|
|
19
|
+
#
|
|
20
|
+
# allowedRouters: [] means all routers are accessible.
|
|
21
|
+
# allowedToolPatterns: [] means all tools are accessible. Supports * wildcard.
|
|
22
|
+
|
|
23
|
+
identities:
|
|
24
|
+
# CI pipeline: operator access to specific routers, limited tool set
|
|
25
|
+
ci-pipeline:
|
|
26
|
+
token: "$2b$12$REPLACE_WITH_BCRYPT_HASH_OF_YOUR_TOKEN"
|
|
27
|
+
role: operator
|
|
28
|
+
allowedRouters:
|
|
29
|
+
- edge-01
|
|
30
|
+
- edge-02
|
|
31
|
+
allowedToolPatterns:
|
|
32
|
+
- "list_*"
|
|
33
|
+
- "ping"
|
|
34
|
+
- "traceroute"
|
|
35
|
+
- "get_system_status"
|
|
36
|
+
|
|
37
|
+
# Admin user: full access to all routers and tools, skips confirmation gate
|
|
38
|
+
admin-ali:
|
|
39
|
+
token: "$2b$12$REPLACE_WITH_BCRYPT_HASH_OF_YOUR_TOKEN"
|
|
40
|
+
role: admin
|
|
41
|
+
allowedRouters: [] # empty = all routers
|
|
42
|
+
allowedToolPatterns: [] # empty = all tools
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# MikroMCP Router Registry
|
|
2
|
+
# Copy to routers.yaml and configure your routers.
|
|
3
|
+
# Credentials are resolved from environment variables by default.
|
|
4
|
+
#
|
|
5
|
+
# Required RouterOS user group policies:
|
|
6
|
+
# read, write, api, rest-api, test, ssh, sniff, ftp
|
|
7
|
+
#
|
|
8
|
+
# The `ftp` policy is required for the upload_file tool.
|
|
9
|
+
# Enable it with:
|
|
10
|
+
# /user group set <group> policy=...,ftp,...
|
|
11
|
+
# FTP service must also be enabled on the router (/ip service enable ftp).
|
|
12
|
+
#
|
|
13
|
+
# The `ssh` policy is required for ping, traceroute, torch, and run_command โ
|
|
14
|
+
# those tools execute via SSH because RouterOS 7.x REST API blocks tool commands
|
|
15
|
+
# regardless of other policy settings.
|
|
16
|
+
# The `sniff` policy is additionally required for torch (packet-capture access).
|
|
17
|
+
#
|
|
18
|
+
# run_command policy modes
|
|
19
|
+
# โโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
20
|
+
# Default (no cmdAllow): All commands allowed except BUILTIN_DENY_PATTERNS.
|
|
21
|
+
# Add cmdDeny entries to block additional patterns.
|
|
22
|
+
# Strict (with cmdAllow): Only commands matching cmdAllow glob patterns are
|
|
23
|
+
# permitted. BUILTIN_DENY_PATTERNS and cmdDeny still apply.
|
|
24
|
+
# Example strict mode:
|
|
25
|
+
# cmdAllow:
|
|
26
|
+
# - "/ip/route/print*"
|
|
27
|
+
# - "/interface/print*"
|
|
28
|
+
# - "/ip/address/print*"
|
|
29
|
+
|
|
30
|
+
routers:
|
|
31
|
+
core-01:
|
|
32
|
+
host: "10.0.0.1"
|
|
33
|
+
port: 443
|
|
34
|
+
tls:
|
|
35
|
+
enabled: true
|
|
36
|
+
rejectUnauthorized: true # Set false ONLY for self-signed certs (logs a warning)
|
|
37
|
+
# ca: "/path/to/ca.pem" # Pin a CA certificate file
|
|
38
|
+
# fingerprint: "aabbccdd..." # Pin exact server cert SHA256 fingerprint (hex, no colons)
|
|
39
|
+
credentials:
|
|
40
|
+
source: "env" # "env" | "vault"
|
|
41
|
+
envPrefix: "ROUTER_CORE01" # -> ROUTER_CORE01_USER, ROUTER_CORE01_PASS
|
|
42
|
+
tags: ["datacenter", "core"]
|
|
43
|
+
rosVersion: "7.14"
|
|
44
|
+
# sshPort: 22 # SSH port (default 22)
|
|
45
|
+
# sshFingerprint: "aabbcc..." # Pin SSH host key SHA256 fingerprint (hex)
|
|
46
|
+
# cmdAllow: # Strict allow-list for run_command (see above)
|
|
47
|
+
# - "/ip/route/print*"
|
|
48
|
+
# cmdDeny: # Additional deny patterns beyond builtins
|
|
49
|
+
# - "/tool/fetch*"
|
|
50
|
+
# maintenanceWindows: # Destructive tools blocked outside these windows
|
|
51
|
+
# - days: ["Sat", "Sun"] # Days when maintenance is permitted
|
|
52
|
+
# startTime: "02:00" # 24-hour HH:MM in the specified timezone
|
|
53
|
+
# endTime: "06:00"
|
|
54
|
+
# timezone: "Europe/Helsinki"
|
|
55
|
+
|
|
56
|
+
# edge-02:
|
|
57
|
+
# host: "192.168.1.1"
|
|
58
|
+
# port: 443
|
|
59
|
+
# tls:
|
|
60
|
+
# enabled: true
|
|
61
|
+
# rejectUnauthorized: false # Self-signed cert โ fingerprint strongly recommended
|
|
62
|
+
# fingerprint: "aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899"
|
|
63
|
+
# credentials:
|
|
64
|
+
# source: "env"
|
|
65
|
+
# envPrefix: "ROUTER_EDGE02"
|
|
66
|
+
# tags: ["branch-office", "edge"]
|
|
67
|
+
# rosVersion: "7.12"
|
|
68
|
+
# sshFingerprint: "aabbccddeeff..."
|