mcp-mikrotik

add_hotspot_user

Creates a MikroTik hotspot voucher user and returns plaintext login credentials plus a QR payload for visitor access. Preview by default, then confirm to apply.

Instructions

Create a hotspot voucher user (/ip/hotspot/user add) for a visitor - name/password are the login credentials; profile (an existing hotspot user profile), limit_uptime (a RouterOS duration, e.g. "01:00:00"), and limit_bytes_total (a positive integer byte quota) are all optional.

QR/VOUCHER: the result always also includes username, password (the plaintext voucher credentials - THIS IS THE POINT: the visitor needs them), and qr_payload - a plain STRING the caller renders as a QR code itself; this package deliberately does NOT generate a QR IMAGE (no extra imaging dependency). Format chosen for qr_payload: "<username>:<password>" - a plain, self-describing credential pair, NOT a login URL and NOT a WIFI: payload. Two alternatives were considered and rejected: a login URL (http://<hotspot>/login?username=..&password=..) would need a reliably-known hotspot LAN address, which this package has no way to determine for an arbitrary device/deployment - and RouterOS's actual captive-portal login is normally a POST with additional session-specific tokens (chap-id/chap-challenge), so a bare GET URL with a plaintext password wouldn't even reliably work; a WIFI: payload is for auto-joining a WPA network, which is a different credential than a hotspot LOGIN (walled-garden HTTP auth) entirely. username:password makes no claim about network topology or login mechanics that could be wrong for a given deployment - a caller integrating with a specific captive portal can build its own login URL from these two fields plus its own known portal address.

PASSWORD IN THE JOURNAL: unlike every secret this package has handled before (a device password, a WireGuard private-key), this tool's password is DELIBERATELY present in its result - but still never written to the audit journal. See guard.add_hotspot_user's docstring for exactly how that asymmetry holds.

WRITE tool, guarded: blocked entirely unless the server is running with MIKROTIK_ALLOW_WRITE=true. Call with confirm=False (the default) to get a preview (including qr_payload) without changing anything; call again with confirm=True to actually create it. Errors clearly (without creating anything) if name already exists on the device - it never creates a duplicate or resets an existing voucher's password.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`name`	Yes
`confirm`	No
`profile`	No
`password`	Yes
`device_name`	Yes
`limit_uptime`	No
`limit_bytes_total`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.11.0Sep 13, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so: it discloses the write-guard requirement, the preview-vs-commit semantics, that duplicates are never created and existing passwords are never reset, and the deliberate password/journal asymmetry. This is unusually rich behavioral disclosure for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and dense with useful facts, but the QR/VOUCHER section spends a full paragraph on two rejected alternatives and their rationale. That design discussion is informative but longer than an agent needs to call the tool, so it dilutes conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a guarded multi-param write tool, nothing essential is missing: creation semantics, guard, preview flow, error behavior, and result fields (username, password, qr_payload) are all addressed. An output schema exists, so the return-value coverage is a bonus rather than a requirement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does: name/password as login credentials, profile as an existing hotspot user profile, limit_uptime as a RouterOS duration with an example, and limit_bytes_total as a positive integer byte quota. confirm is covered in the workflow and the optional/required split is clear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Create a hotspot voucher user') with the underlying RouterOS path (`/ip/hotspot/user add`) and the target audience (a visitor). It is unambiguous against siblings like hotspot_active, which reads rather than creates users.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states prerequisites (blocked unless MIKROTIK_ALLOW_WRITE=true) and the exact two-call workflow: confirm=False for a preview, confirm=True to create. It also spells out the name-collision behavior, so an agent knows the intended call sequence and the failure mode.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server