mikromcp 1.5.0 โ 1.6.1
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 +60 -346
- package/dist/main.js +1643 -1310
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -12,12 +12,12 @@
|
|
|
12
12
|
|
|
13
13
|
[](https://github.com/AliKarami/MikroMCP/actions/workflows/ci.yml)
|
|
14
14
|
[](https://github.com/AliKarami/MikroMCP/actions/workflows/release.yml)
|
|
15
|
-
[](package.json)
|
|
16
16
|
[](LICENSE)
|
|
17
17
|
[](package.json)
|
|
18
18
|
[](https://help.mikrotik.com/docs/display/ROS/REST+API)
|
|
19
19
|
[](https://modelcontextprotocol.io)
|
|
20
|
-
[](
|
|
20
|
+
[](https://github.com/AliKarami/MikroMCP/wiki/Available-Tools)
|
|
21
21
|
[](https://glama.ai/mcp/servers/AliKarami/MikroMCP)
|
|
22
22
|
|
|
23
23
|
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.
|
|
@@ -28,15 +28,13 @@ MikroMCP exists because raw router CLI access is the wrong abstraction for AI ag
|
|
|
28
28
|
|
|
29
29
|
---
|
|
30
30
|
|
|
31
|
-
##
|
|
31
|
+
## Quick Start
|
|
32
32
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
| Raw network access for every assistant | RBAC identities, bearer tokens for HTTP mode, tool allowlists, and audit trails |
|
|
39
|
-
| Fragile troubleshooting workflows | Router-originated ping, traceroute, torch, logs, interfaces, DHCP, firewall, routes, WiFi, WireGuard, and more |
|
|
33
|
+
<p align="center">
|
|
34
|
+
<img src="docs/assets/quickstart.svg" alt="MikroMCP quick start: npm install -g mikromcp, mikromcp init, then ask Claude Desktop about your router" width="760">
|
|
35
|
+
</p>
|
|
36
|
+
|
|
37
|
+
That's the whole setup for a single-router stdio deployment. For standalone binaries, Docker, HTTP/SSE mode, the RouterOS API prerequisites, and the full 15-minute walkthrough, see the **[Getting Started guide](https://github.com/AliKarami/MikroMCP/wiki/Getting-Started)**.
|
|
40
38
|
|
|
41
39
|
---
|
|
42
40
|
|
|
@@ -52,9 +50,11 @@ MikroMCP exists because raw router CLI access is the wrong abstraction for AI ag
|
|
|
52
50
|
| ๐งช **Diagnostics** | Router-originated `ping`, `traceroute`, `torch`, log filtering, guarded SSH command execution |
|
|
53
51
|
| ๐ก๏ธ **Change safety** | Dry-run, idempotent writes, snapshots, write journal, `plan_changes`, `apply_plan`, `rollback_change` |
|
|
54
52
|
| โ๏ธ **Production behavior** | Retries for read tools, per-router circuit breakers, correlation IDs, structured logs, audit logs |
|
|
55
|
-
| ๐ค **AI-agent fit** | Human-readable responses plus structured JSON content for reasoning, chaining, and automation
|
|
53
|
+
| ๐ค **AI-agent fit** | Human-readable responses plus structured JSON content for reasoning, chaining, and automation; server advertises an `instructions` string on MCP initialize so clients self-configure; optional [`routerId` resolved via `MIKROMCP_DEFAULT_ROUTER`](https://github.com/AliKarami/MikroMCP/wiki/Configuration) for single-router setups; [usage skill](docs/wiki/Using-the-Skill.md) for safe, guided tool use in Claude Code |
|
|
56
54
|
| ๐งฉ **MCP compatibility** | stdio for desktop clients, Streamable HTTP and legacy SSE for remote or service-style clients |
|
|
57
55
|
|
|
56
|
+
**117 typed tools** in total โ browse the full catalog with parameters, defaults, and copy-paste example prompts in **[Available Tools](https://github.com/AliKarami/MikroMCP/wiki/Available-Tools)**.
|
|
57
|
+
|
|
58
58
|
---
|
|
59
59
|
|
|
60
60
|
## Demo
|
|
@@ -69,284 +69,6 @@ MikroMCP exists because raw router CLI access is the wrong abstraction for AI ag
|
|
|
69
69
|
|
|
70
70
|
|
|
71
71
|
|
|
72
|
-
### MCP Inspector
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
---
|
|
77
|
-
|
|
78
|
-
## Quick Start
|
|
79
|
-
|
|
80
|
-
### Prerequisites
|
|
81
|
-
|
|
82
|
-
- Node.js 22 or newer (for npm install) โ or use a standalone binary below
|
|
83
|
-
- MikroTik RouterOS 7.x with the REST API enabled
|
|
84
|
-
- A RouterOS user with the policies your tools require
|
|
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
|
-
> `ssh` is required for `ping`, `traceroute`, `torch`, and `run_command`. `sniff` is required by `torch`. `ftp` is required only for `upload_file`.
|
|
93
|
-
|
|
94
|
-
---
|
|
95
|
-
|
|
96
|
-
### Install
|
|
97
|
-
|
|
98
|
-
**npm (recommended)**
|
|
99
|
-
|
|
100
|
-
```bash
|
|
101
|
-
npm install -g mikromcp
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
**Standalone binaries**
|
|
105
|
-
|
|
106
|
-
Download the binary for your platform from the [latest GitHub release](https://github.com/AliKarami/MikroMCP/releases/latest) โ no Node.js required.
|
|
107
|
-
|
|
108
|
-
**Docker**
|
|
109
|
-
|
|
110
|
-
```bash
|
|
111
|
-
docker pull ghcr.io/alikarami/mikromcp:latest
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
---
|
|
115
|
-
|
|
116
|
-
### Set Up With the Init Wizard
|
|
117
|
-
|
|
118
|
-
Run the interactive setup wizard:
|
|
119
|
-
|
|
120
|
-
```bash
|
|
121
|
-
mikromcp init
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
The wizard will ask for your router details and write everything to `~/.mikromcp/`:
|
|
125
|
-
|
|
126
|
-
```
|
|
127
|
-
~/.mikromcp/
|
|
128
|
-
โโโ routers.yaml # router registry
|
|
129
|
-
โโโ identities.yaml # RBAC identities (HTTP mode)
|
|
130
|
-
โโโ .env # credentials and runtime settings
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
`~/.mikromcp/.env` is loaded automatically every time MikroMCP starts โ no shell exports or Claude Desktop `env` blocks needed. Fill in the credentials it generates:
|
|
134
|
-
|
|
135
|
-
```bash
|
|
136
|
-
# ~/.mikromcp/.env (generated by mikromcp init)
|
|
137
|
-
ROUTER_CORE01_USER=
|
|
138
|
-
ROUTER_CORE01_PASS=
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
To edit your router registry directly:
|
|
142
|
-
|
|
143
|
-
```bash
|
|
144
|
-
nano ~/.mikromcp/routers.yaml
|
|
145
|
-
```
|
|
146
|
-
|
|
147
|
-
```yaml
|
|
148
|
-
routers:
|
|
149
|
-
core-01:
|
|
150
|
-
host: "192.168.88.1"
|
|
151
|
-
port: 443
|
|
152
|
-
tls:
|
|
153
|
-
enabled: true
|
|
154
|
-
rejectUnauthorized: true
|
|
155
|
-
credentials:
|
|
156
|
-
source: "env"
|
|
157
|
-
envPrefix: "ROUTER_CORE01"
|
|
158
|
-
tags: ["core"]
|
|
159
|
-
rosVersion: "7"
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
---
|
|
163
|
-
|
|
164
|
-
### Verify With Doctor
|
|
165
|
-
|
|
166
|
-
```bash
|
|
167
|
-
mikromcp doctor
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
Doctor checks Node version, config files, router reachability, Claude Desktop registration, and whether a newer version is available.
|
|
171
|
-
|
|
172
|
-
---
|
|
173
|
-
|
|
174
|
-
### Run
|
|
175
|
-
|
|
176
|
-
**stdio (for Claude Desktop and other desktop MCP clients)**
|
|
177
|
-
|
|
178
|
-
```bash
|
|
179
|
-
mikromcp serve
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
**HTTP mode (for service deployments)**
|
|
183
|
-
|
|
184
|
-
```bash
|
|
185
|
-
MIKROMCP_TRANSPORT=http mikromcp serve
|
|
186
|
-
```
|
|
187
|
-
|
|
188
|
-
---
|
|
189
|
-
|
|
190
|
-
## Connect An MCP Client
|
|
191
|
-
|
|
192
|
-
### Claude Desktop
|
|
193
|
-
|
|
194
|
-
Run `mikromcp init` and choose **Register with Claude Desktop** โ it patches `claude_desktop_config.json` automatically.
|
|
195
|
-
|
|
196
|
-
Or add it manually to `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS:
|
|
197
|
-
|
|
198
|
-
```json
|
|
199
|
-
{
|
|
200
|
-
"mcpServers": {
|
|
201
|
-
"mikromcp": {
|
|
202
|
-
"command": "mikromcp",
|
|
203
|
-
"args": ["serve"]
|
|
204
|
-
}
|
|
205
|
-
}
|
|
206
|
-
}
|
|
207
|
-
```
|
|
208
|
-
|
|
209
|
-
No `env` block needed โ credentials are loaded from `~/.mikromcp/.env` at startup. Restart Claude Desktop, then ask:
|
|
210
|
-
|
|
211
|
-
```text
|
|
212
|
-
Use MikroMCP to show CPU, memory, uptime, active interfaces, and warning logs for core-01.
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
### HTTP / SSE Mode
|
|
216
|
-
|
|
217
|
-
HTTP mode is useful for service deployments and MCP clients that connect over a network endpoint.
|
|
218
|
-
|
|
219
|
-
Set in `~/.mikromcp/.env`:
|
|
220
|
-
|
|
221
|
-
```bash
|
|
222
|
-
MIKROMCP_TRANSPORT=http
|
|
223
|
-
MIKROMCP_PORT=3000
|
|
224
|
-
MIKROMCP_CONFIRMATION_SECRET=<openssl rand -hex 32>
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
Then run:
|
|
228
|
-
|
|
229
|
-
```bash
|
|
230
|
-
mikromcp serve
|
|
231
|
-
```
|
|
232
|
-
|
|
233
|
-
Every HTTP request must include:
|
|
234
|
-
|
|
235
|
-
```text
|
|
236
|
-
Authorization: Bearer <token>
|
|
237
|
-
```
|
|
238
|
-
|
|
239
|
-
Tokens are configured as bcrypt hashes in `~/.mikromcp/identities.yaml`. Use `mikromcp init` to generate them.
|
|
240
|
-
|
|
241
|
-
### Docker
|
|
242
|
-
|
|
243
|
-
```bash
|
|
244
|
-
docker run --rm \
|
|
245
|
-
-e MIKROMCP_TRANSPORT=http \
|
|
246
|
-
-e MIKROMCP_PORT=3000 \
|
|
247
|
-
-e MIKROMCP_CONFIRMATION_SECRET="$(openssl rand -hex 32)" \
|
|
248
|
-
-e ROUTER_CORE01_USER=mcp-api \
|
|
249
|
-
-e ROUTER_CORE01_PASS=your-router-password \
|
|
250
|
-
-e MIKROMCP_CONFIG_PATH=/config/routers.yaml \
|
|
251
|
-
-v "$HOME/.mikromcp:/config:ro" \
|
|
252
|
-
-p 3000:3000 \
|
|
253
|
-
ghcr.io/alikarami/mikromcp:latest
|
|
254
|
-
```
|
|
255
|
-
|
|
256
|
-
Pass `MIKROMCP_CONFIG_PATH` and `MIKROMCP_IDENTITIES_PATH` explicitly when running in Docker since `~/.mikromcp/` inside the container refers to the container's home directory.
|
|
257
|
-
|
|
258
|
-
---
|
|
259
|
-
|
|
260
|
-
## Configuration Reference
|
|
261
|
-
|
|
262
|
-
All settings can be placed in `~/.mikromcp/.env` or passed as environment variables. Values in `~/.mikromcp/.env` are loaded at startup; explicit environment variables always take precedence.
|
|
263
|
-
|
|
264
|
-
| Variable | Default | Purpose |
|
|
265
|
-
| --------------------------------- | -------------------------------- | ------------------------------------------------------ |
|
|
266
|
-
| `MIKROMCP_TRANSPORT` | `stdio` | `stdio` or `http` |
|
|
267
|
-
| `MIKROMCP_CONFIG_PATH` | `~/.mikromcp/routers.yaml` | Router registry path |
|
|
268
|
-
| `MIKROMCP_IDENTITIES_PATH` | `~/.mikromcp/identities.yaml` | Identity and bearer-token registry |
|
|
269
|
-
| `MIKROMCP_STDIO_IDENTITY` | built-in superadmin | Named identity for stdio mode |
|
|
270
|
-
| `MIKROMCP_PORT` | `3000` | HTTP transport port |
|
|
271
|
-
| `MIKROMCP_BIND_HOST` | `127.0.0.1` | HTTP bind address |
|
|
272
|
-
| `MIKROMCP_CONFIRMATION_SECRET` | unset | HMAC secret for destructive-action confirmation tokens |
|
|
273
|
-
| `MIKROMCP_AUDIT_LOG_PATH` | unset | Optional NDJSON audit log file path |
|
|
274
|
-
| `MIKROMCP_DATA_DIR` | `~/.mikromcp/data` | Snapshots and write-journal directory |
|
|
275
|
-
| `MIKROMCP_HTTP_MAX_BODY_BYTES` | `1048576` | HTTP request body cap |
|
|
276
|
-
| `MIKROMCP_HTTP_RATE_LIMIT_RPM` | `60` | Requests per minute per IP; `0` disables rate limiting |
|
|
277
|
-
| `MIKROMCP_SSH_COMMAND_TIMEOUT_MS` | `30000` | SSH command timeout |
|
|
278
|
-
| `MIKROMCP_SSH_MAX_OUTPUT_BYTES` | `524288` | SSH output cap |
|
|
279
|
-
| `MIKROMCP_CMD_ALLOW` | unset | Global allowlist patterns for `run_command` |
|
|
280
|
-
| `MIKROMCP_CMD_DENY` | unset | Global denylist patterns for `run_command` |
|
|
281
|
-
| `ROUTER_<PREFIX>_USER` | unset | Router username from `envPrefix` |
|
|
282
|
-
| `ROUTER_<PREFIX>_PASS` | unset | Router password from `envPrefix` |
|
|
283
|
-
|
|
284
|
-
---
|
|
285
|
-
|
|
286
|
-
## Available Tools
|
|
287
|
-
|
|
288
|
-
MikroMCP currently registers **117 MCP tools**.
|
|
289
|
-
|
|
290
|
-
| Area | Tools |
|
|
291
|
-
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
292
|
-
| System | `get_system_status`, `get_system_clock`, `set_system_clock`, `reboot` |
|
|
293
|
-
| Interfaces and IP | `list_interfaces`, `manage_vlan`, `manage_ip_address` |
|
|
294
|
-
| DHCP and DNS | `list_dhcp_leases`, `manage_dhcp_lease`, `list_dns_entries`, `manage_dns_entry`, `get_dns_settings`, `manage_dns_settings` |
|
|
295
|
-
| DHCP Servers & Pools | `list_dhcp_servers`, `manage_dhcp_server`, `list_ip_pools`, `manage_ip_pool` |
|
|
296
|
-
| DHCP Clients | `list_dhcp_clients`, `manage_dhcp_client` |
|
|
297
|
-
| IP Services | `list_ip_services`, `manage_ip_service` |
|
|
298
|
-
| PPPoE & OpenVPN | `list_pppoe_clients`, `manage_pppoe_client`, `list_ovpn_clients`, `manage_ovpn_client`, `get_ovpn_server`, `manage_ovpn_server` |
|
|
299
|
-
| PPP Profiles | `list_ppp_profiles`, `manage_ppp_profile` |
|
|
300
|
-
| Routing | `list_routes`, `manage_route`, `list_routing_rules`, `manage_routing_rule`, `list_routing_tables`, `manage_routing_table` |
|
|
301
|
-
| Routing protocols | `list_bgp_peers`, `list_ospf_neighbors` |
|
|
302
|
-
| Firewall | `list_firewall_rules`, `manage_firewall_rule`, `list_mangle_rules`, `manage_mangle_rule`, `list_address_list_entries`, `manage_address_list_entry`, `list_interface_lists`, `manage_interface_list`, `manage_interface_list_member` |
|
|
303
|
-
| 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`, `manage_wireguard_interface` |
|
|
304
|
-
| IPSec/VPN | `list_ipsec_peers`, `list_ipsec_policies`, `manage_ipsec_peer`, `manage_ipsec_policy` |
|
|
305
|
-
| Certificates | `list_certificates`, `manage_certificate` |
|
|
306
|
-
| Users | `list_users`, `manage_user` |
|
|
307
|
-
| Queues/QoS | `list_queues`, `manage_queue` |
|
|
308
|
-
| VRRP | `list_vrrp_instances`, `manage_vrrp_instance` |
|
|
309
|
-
| SNMP & NTP | `get_snmp_settings`, `get_ntp_settings` |
|
|
310
|
-
| Netwatch | `list_netwatch_entries`, `manage_netwatch_entry` |
|
|
311
|
-
| Discovery & ARP | `list_neighbors`, `list_arp_entries` |
|
|
312
|
-
| Diagnostics | `ping`, `traceroute`, `torch`, `get_log`, `run_command`, `bandwidth_test`, `fetch_url`, `list_connections` |
|
|
313
|
-
| Automation | `list_scripts`, `manage_script`, `run_script`, `list_scheduled_jobs`, `manage_scheduled_job` |
|
|
314
|
-
| Runtime | `list_packages`, `manage_package`, `list_files`, `get_file_content`, `upload_file`, `delete_file`, `list_containers`, `manage_container`, `get_container_config`, `manage_container_config`, `list_container_envs`, `manage_container_env`, `list_container_mounts`, `manage_container_mount` |
|
|
315
|
-
| Change management | `plan_changes`, `apply_plan`, `rollback_change` |
|
|
316
|
-
| Fleet operations | `check_router_health`, `bulk_execute` |
|
|
317
|
-
|
|
318
|
-
```mermaid
|
|
319
|
-
mindmap
|
|
320
|
-
root((MikroMCP tools))
|
|
321
|
-
Operations
|
|
322
|
-
System status
|
|
323
|
-
Logs
|
|
324
|
-
Clock
|
|
325
|
-
Reboot
|
|
326
|
-
Network
|
|
327
|
-
Interfaces
|
|
328
|
-
VLANs
|
|
329
|
-
DHCP
|
|
330
|
-
DNS
|
|
331
|
-
WiFi
|
|
332
|
-
WireGuard
|
|
333
|
-
Policy
|
|
334
|
-
Firewall
|
|
335
|
-
NAT
|
|
336
|
-
Mangle
|
|
337
|
-
Address lists
|
|
338
|
-
Routing rules
|
|
339
|
-
Automation
|
|
340
|
-
Scripts
|
|
341
|
-
Scheduler
|
|
342
|
-
Files
|
|
343
|
-
Containers
|
|
344
|
-
Safety
|
|
345
|
-
Plan changes
|
|
346
|
-
Apply plan
|
|
347
|
-
Rollback change
|
|
348
|
-
```
|
|
349
|
-
|
|
350
72
|
---
|
|
351
73
|
|
|
352
74
|
## Real-World Usage Examples
|
|
@@ -413,64 +135,66 @@ AI assistants can use MikroMCP to:
|
|
|
413
135
|
|
|
414
136
|
---
|
|
415
137
|
|
|
138
|
+
## FAQ
|
|
139
|
+
|
|
140
|
+
### What is MikroMCP?
|
|
141
|
+
|
|
142
|
+
MikroMCP is an open-source [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that exposes MikroTik RouterOS as 117 typed, auditable tools โ letting AI assistants inspect, diagnose, and safely operate routers in natural language instead of improvising CLI commands.
|
|
143
|
+
|
|
144
|
+
### MikroMCP vs RouterOS API
|
|
145
|
+
|
|
146
|
+
The RouterOS REST/API exposes raw endpoints. MikroMCP wraps them in schema-validated, idempotent, dry-run-able tools with RBAC, audit logging, snapshots, and rollback โ the safety layer an LLM needs before it touches production gear.
|
|
147
|
+
|
|
148
|
+
### MikroMCP vs SSH automation
|
|
149
|
+
|
|
150
|
+
Instead of brittle SSH scripts that screen-scrape CLI output, MikroMCP returns structured, typed results with confirmation gates and per-router circuit breakers. SSH is used only where REST can't reach โ `ping`, `traceroute`, `torch`, and guarded `run_command`.
|
|
151
|
+
|
|
152
|
+
### MikroMCP for Claude Code
|
|
153
|
+
|
|
154
|
+
MikroMCP speaks MCP over stdio and HTTP/SSE, so Claude Code and Claude Desktop drive RouterOS directly. Pair it with the bundled [usage skill](docs/wiki/Using-the-Skill.md) for safe, guided workflows.
|
|
155
|
+
|
|
156
|
+
### MikroMCP for Codex
|
|
157
|
+
|
|
158
|
+
Codex connects to MikroMCP over the standard MCP protocol โ see [Connecting to AI Assistants](https://github.com/AliKarami/MikroMCP/wiki/Connecting-to-AI-Assistants).
|
|
159
|
+
|
|
160
|
+
### MikroMCP for Cursor
|
|
161
|
+
|
|
162
|
+
Cursor connects to MikroMCP as an MCP server (stdio or HTTP) to inspect and manage MikroTik routers without leaving the editor.
|
|
163
|
+
|
|
164
|
+
### MikroMCP for OpenClaw
|
|
165
|
+
|
|
166
|
+
Any MCP-compatible client โ OpenClaw included โ can use MikroMCP; configure it as a stdio or HTTP MCP server.
|
|
167
|
+
|
|
168
|
+
### RouterOS AI Automation Guide
|
|
169
|
+
|
|
170
|
+
Start with [Getting Started](https://github.com/AliKarami/MikroMCP/wiki/Getting-Started) to install and connect, then use the [usage skill](docs/wiki/Using-the-Skill.md) and [Available Tools](https://github.com/AliKarami/MikroMCP/wiki/Available-Tools) to automate RouterOS safely with an AI assistant.
|
|
171
|
+
|
|
172
|
+
### Best MCP Servers for Network Engineers
|
|
173
|
+
|
|
174
|
+
MikroMCP is purpose-built for MikroTik/RouterOS operations with production-grade safety โ dry-run, rollback, audit, and RBAC โ making it a strong MCP choice for network engineers adopting AI tooling.
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
416
178
|
## Documentation
|
|
417
179
|
|
|
180
|
+
The README stays intentionally short. Everything below is documented in depth in the [wiki](https://github.com/AliKarami/MikroMCP/wiki):
|
|
181
|
+
|
|
418
182
|
| Resource | Use it for |
|
|
419
183
|
| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
|
|
420
|
-
| [
|
|
421
|
-
| [Getting Started](https://github.com/AliKarami/MikroMCP/wiki/Getting-Started) | Install, configure, and connect in 15 minutes |
|
|
184
|
+
| [Getting Started](https://github.com/AliKarami/MikroMCP/wiki/Getting-Started) | Install (npm, binary, Docker), configure, and connect in 15 minutes |
|
|
422
185
|
| [RouterOS API Setup](https://github.com/AliKarami/MikroMCP/wiki/RouterOS-API-Setup) | Enable the REST API, create a user, TLS and firewall |
|
|
423
186
|
| [Configuration](https://github.com/AliKarami/MikroMCP/wiki/Configuration) | Router registry, credentials, all environment variables |
|
|
187
|
+
| [Running](https://github.com/AliKarami/MikroMCP/wiki/Running) | Run commands, HTTP/SSE transport, troubleshooting |
|
|
424
188
|
| [Connecting to Claude Desktop](https://github.com/AliKarami/MikroMCP/wiki/Connecting-to-Claude-Desktop) | Register MikroMCP in Claude Desktop |
|
|
425
189
|
| [Connecting to AI Assistants](https://github.com/AliKarami/MikroMCP/wiki/Connecting-to-AI-Assistants) | Claude Code, Cursor, Codex, HTTP/Docker/systemd |
|
|
426
|
-
| [
|
|
190
|
+
| [Using the Skill](docs/wiki/Using-the-Skill.md) | Install the MikroMCP usage skill so your assistant drives the tools safely |
|
|
191
|
+
| [Available Tools](https://github.com/AliKarami/MikroMCP/wiki/Available-Tools) | All 117 tools โ parameters and example prompts |
|
|
427
192
|
| [Architecture](https://github.com/AliKarami/MikroMCP/wiki/Architecture) | System layers, request pipeline, auth model |
|
|
428
193
|
| [Error Handling](https://github.com/AliKarami/MikroMCP/wiki/Error-Handling) | Error categories, retry engine, circuit breaker |
|
|
429
|
-
| [
|
|
194
|
+
| [Security](https://github.com/AliKarami/MikroMCP/wiki/Security) | Threat model, hardening checklist, vulnerability reporting |
|
|
430
195
|
| [Development](https://github.com/AliKarami/MikroMCP/wiki/Development) | Project structure, tests, MCP Inspector workflow |
|
|
431
196
|
| [Contributing](https://github.com/AliKarami/MikroMCP/wiki/Contributing) | Adding tools, coding conventions, PR checklist |
|
|
432
|
-
|
|
433
|
-
---
|
|
434
|
-
|
|
435
|
-
## Development
|
|
436
|
-
|
|
437
|
-
```bash
|
|
438
|
-
npm run dev # tsx watch hot-reload
|
|
439
|
-
npm run build # build ESM output to dist/main.js
|
|
440
|
-
npm start # run built server
|
|
441
|
-
npm test # vitest + tsc + eslint
|
|
442
|
-
npm run format # Prettier
|
|
443
|
-
```
|
|
444
|
-
|
|
445
|
-
Key project paths:
|
|
446
|
-
|
|
447
|
-
| Path | Purpose |
|
|
448
|
-
| -------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
449
|
-
| `src/main.ts` | Loads `~/.mikromcp/.env` and starts stdio or HTTP transport |
|
|
450
|
-
| `src/mcp/tool-registry.ts` | Registers tools and applies auth, retry, circuit breaker, audit, snapshots, and credentials |
|
|
451
|
-
| `src/domain/tools/` | Tool definitions and handlers |
|
|
452
|
-
| `src/domain/snapshot/` | Snapshot, diff, and write-journal support |
|
|
453
|
-
| `src/adapter/rest-client.ts` | RouterOS REST API client |
|
|
454
|
-
| `src/adapter/ssh-client.ts` | SSH execution adapter for diagnostics and guarded commands |
|
|
455
|
-
| `src/config/router-registry.ts` | Router inventory loader |
|
|
456
|
-
| `src/cli/init.ts` | Interactive setup wizard (`mikromcp init`) |
|
|
457
|
-
| `src/cli/doctor.ts` | Health check command (`mikromcp doctor`) |
|
|
458
|
-
| `config/routers.example.yaml` | Example multi-router registry |
|
|
459
|
-
| `config/identities.example.yaml` | Example RBAC identity registry |
|
|
460
|
-
|
|
461
|
-
---
|
|
462
|
-
|
|
463
|
-
## Roadmap
|
|
464
|
-
|
|
465
|
-
| Milestone | Status | Focus |
|
|
466
|
-
| --------- | ---------- | -------------------------------------------------------------------------------------------------------- |
|
|
467
|
-
| v0.1-v0.6 | โ
Shipped | Foundation, core tools, diagnostics, services, firewall, routing, automation, files, containers |
|
|
468
|
-
| v0.7 | โ
Shipped | Identity, bearer auth, RBAC, audit log, confirmation gate |
|
|
469
|
-
| v0.8 | โ
Shipped | Snapshots, write journal, plan/apply, rollback, maintenance windows |
|
|
470
|
-
| v0.9 | โ
Shipped | Fleet operations, IPSec, certificates, users, DHCP servers/pools, queues/QoS, VRRP, SNMP/NTP, Netwatch, discovery, ARP, health checks |
|
|
471
|
-
| v1.0 | โ
Shipped | npm package, standalone binaries, Docker images, `mikromcp init` wizard, `mikromcp doctor`, `~/.mikromcp/` convention |
|
|
472
|
-
|
|
473
|
-
See [ROADMAP.md](ROADMAP.md) for the complete milestone plan.
|
|
197
|
+
| [Roadmap](https://github.com/AliKarami/MikroMCP/wiki/Roadmap) ยท [ROADMAP.md](ROADMAP.md) | Shipped milestones and guiding principles |
|
|
474
198
|
|
|
475
199
|
---
|
|
476
200
|
|
|
@@ -497,17 +221,7 @@ Please open an issue before large changes so maintainers can align on scope.
|
|
|
497
221
|
|
|
498
222
|
## Security
|
|
499
223
|
|
|
500
|
-
MikroMCP controls real network devices
|
|
501
|
-
|
|
502
|
-
- Use least-privilege RouterOS users.
|
|
503
|
-
- Prefer TLS verification and certificate fingerprint pinning.
|
|
504
|
-
- Keep router credentials in `~/.mikromcp/.env`, not in YAML or shell history.
|
|
505
|
-
- Use HTTP mode behind a trusted network boundary.
|
|
506
|
-
- Configure identities with the smallest practical `allowedRouters` and `allowedToolPatterns`.
|
|
507
|
-
- Enable audit logging (`MIKROMCP_AUDIT_LOG_PATH`) for shared or production use.
|
|
508
|
-
- Test write tools with `dryRun: true` before applying changes.
|
|
509
|
-
|
|
510
|
-
For vulnerabilities or unsafe behavior, open a private security advisory or contact the maintainer before publishing details.
|
|
224
|
+
MikroMCP controls real network devices โ treat it like an operations system: least-privilege RouterOS users, verified TLS (or pinned fingerprints), credentials only in `~/.mikromcp/.env`, scoped RBAC identities, and audit logging for shared use. The full hardening checklist and vulnerability-reporting process are on the [Security page](https://github.com/AliKarami/MikroMCP/wiki/Security).
|
|
511
225
|
|
|
512
226
|
---
|
|
513
227
|
|