MKTXP is an extensible toolkit for MikroTik RouterOS network engineering. It provides interactive terminal diagnostics, deterministic GitOps configuration management, and a Prometheus metrics exporter within a single command-line tool.
| I need to … | Start with | Full Guide |
|---|---|---|
| Troubleshoot a router now | mktxp diag … |
CLI Diagnostics Guide |
| Clean up / version RouterOS configs | mktxp rsc … |
GitOps RSC Guide |
| Monitor routers continuously | mktxp export |
Prometheus Exporter Guide |
# Recommended for local CLI usage
❯ pipx install mktxp
# Or via standard pip
❯ pip install mktxp
# Via Homebrew
❯ brew install mktxp
# Via Docker
❯ docker pull ghcr.io/akpw/mktxp:latestRequirements: Python >= 3.9. Supported on Linux, macOS, and FreeBSD.
If you need a turnkey environment without manually wiring services, MKTXP Stack is an out-of-the-box Docker Compose deployment that packages MKTXP alongside Prometheus / Grafana stack with pre-configured dashboards, and adds centralized MikroTik syslog processing via Loki and Promtail.
For local .rsc files, mktxp rsc works with zero configuration or router setup required:
# Deterministic formatting: single-line commands, standardized headers, and clean Git diffs
❯ mktxp rsc format -i backup.rsc -o clean_backup.rsc
# Modular domain splitting: break a monolithic export into numbered component files and extracted scripts
❯ mktxp rsc split -i backup.rsc -o ./config-repo/ --extract-scripts📖 For AST architecture, custom domain handlers, live backups over SSH, and CI/CD automation, see the GitOps RSC Guide.
Both Live Diagnostics and the Prometheus Exporter connect to your routers via the standard RouterOS API.
MKTXP uses two configuration files:
mktxp.conf: Router connection profiles, credentials, custom labels, and metrics switches. Edit withmktxp edit._mktxp.conf: Daemon listen sockets, timeouts, parallel scraping, GitOps rules, and CLI diagnostic thresholds. Edit withmktxp edit -i.
Files are resolved automatically from ~/.config/mktxp/ (XDG standard) or /etc/mktxp/ (system/Docker). Check active paths anytime with mktxp show -cfg.
Add your router entry to mktxp.conf:
[My-Router]
hostname = 192.168.88.1
username = mktxp_user
password = secret_password(For Docker, simply mount your config directory: -v "$(pwd)/mktxp-config:/etc/mktxp")
Create a dedicated monitoring user on your MikroTik router:
/user group add name=mktxp_group policy=api,read
/user add name=mktxp_user group=mktxp_group password=secret_password
(Note: For LTE metrics on RouterOS v6, the user also needs the test permission policy.)
📖 For complete parameter references,
[default]section inheritance, custom labels, parallel fetching, and diagnostic tuning, see the Configuration Guide.
Run targeted, domain-specific diagnostic one-liners directly in your terminal:
# Find sticky wireless clients clinging to distant APs with poor signal or low rates
❯ mktxp diag -en My-Router -cc --low-signal --low-rate 1M
# Surface top bandwidth consumers across the network
❯ mktxp diag -en My-Router -kc --top 5
# Audit mystery DHCP devices with no hostname
❯ mktxp diag -en My-Router -dc --unidentified
# Check active dynamic firewall threat bans
❯ mktxp diag -en My-Router -al blacklist --dynamic-only
# Pinpoint degraded cables or ports negotiating down (< 100 Mbps or half-duplex)
❯ mktxp diag -en My-Router -im --degradedSample output:
+----------------------+--------------+-------------------+-----------+------------------+--------+---------+---------+---------+
| dhcp_name | dhcp_address | mac_address | rx_signal | interface | ssid | tx_rate | rx_rate | uptime |
+======================+==============+===================+===========+==================+========+=========+=========+=========+
| wlan0 (Conf Printer) | 10.20.10.49 | D8:1F:12:AD:3C:55 | -87 | AP-Breakroom-2G | Office | 36 Mbps | 1 Mbps | 6 hours |
| wlan0 (Boardroom Tab)| 10.20.10.97 | 10:5A:17:0C:B9:C8 | -84 | AP-Reception-2G | Office | 24 Mbps | 1 Mbps | a day |
+----------------------+--------------+-------------------+-----------+------------------+--------+---------+---------+---------+
Matching CAPsMAN clients: 2 (Total connected: 127)
💡 Tip: Appending
-hto any command (e.g.mktxp diag -kc -h) dynamically scopes help to only that command's filters.
📖 For more diagnostic domains, table schemas, and recipes, see the Diagnostics Guide.
Start the exporter daemon to scrape configured routers and serve metrics to Prometheus:
❯ mktxp export
# Serving Prometheus metrics at http://localhost:49090/metricsAdd the scrape target to /etc/prometheus/prometheus.yml:
scrape_configs:
- job_name: 'mktxp'
static_configs:
- targets: ['localhost:49090']Import the official Grafana Dashboard (ID: 13679):
💡 Tip: Want centralized RouterOS logs too? MKTXP Stack is an out-of-the-box Docker Compose deployment that packages MKTXP alongside Prometheus / Grafana stack with pre-configured dashboards, and adds centralized MikroTik syslog processing via Loki and Promtail.
💡 Tip: 📖 For dynamic multi-target discovery (
/probe), Docker/Kubernetes, and systemd/FreeBSD service deployment, see the Exporter Guide.
- Live CLI Diagnostics Guide: Detailed filter reference, table schemas, and recipes for multiple diagnostic domains.
- RouterOS GitOps RSC Guide: AST formatting, modular domain splitting, script extraction, and CI/CD pipelines.
- Prometheus Exporter Guide: Metrics catalog,
/probemulti-target pattern, container manifests, and service files. - Configuration Reference Guide: Complete anatomy of
mktxp.confand_mktxp.conf, multi-router inheritance, tuning, and Docker mounts.
- Beyond Metrics: Instant RouterOS Diagnostics with MKTXP 2.0
- Under the Hood: Refactoring MKTXP for 2.0
- Wrangling RouterOS Configs: Introducing GitOps for MikroTik with MKTXP
- Distributed under the GNU General Public License v2.
- Local development:
- Create a virtual environment:
python3 -m venv .venv && source .venv/bin/activate - Install editable with test dependencies:
pip install -e ".[test]" - Run test suite:
pytest - Install latest development build directly:
pip install git+https://github.com/akpw/mktxp
- Create a virtual environment: