/unifi-network-setup

name: unifi-network-setup
description: Configure the UniFi Network MCP server for a supported MCP client — set controller host, credentials, and permissions. Also use when the unifi-network server failed to start or its tools are missing, especially right after a plugin update, because in Claude Code the plugin no longer reads settings an earlier version saved in the project's .claude/settings.local.json, and this skill migrates them
allowed-tools: Read, Bash, AskUserQuestion

Set Up UniFi Network MCP Server

Walk the user through configuring their UniFi Network controller connection. Ask one question at a time and wait for the answer before continuing.

Interaction Rules

Use the client target that matches the current agent runtime:

• Claude Code: `claude`
• Codex: `codex`
• OpenClaw: `openclaw`

If the runtime is unclear, ask which client to configure. For questions, use the platform's blocking question tool when available (`AskUserQuestion` in Claude Code, `request_user_input` in Codex). If no blocking question tool is available, ask in chat with numbered options and wait for the user's reply.

This skill may come from a complete UniFi plugin or a standalone `npx skills` install. Before using a helper script, verify that the plugin's `scripts/` directory exists. If it does not, do not guess a relative path: follow the [canonical agent installation guide](https://github.com/sirkirby/unifi-mcp/blob/main/docs/agent-install.md) for the client's native MCP registration path. That guide covers OpenCode, Antigravity, Devin Desktop, Cursor, and other manual clients. A standalone skill install does not install or register the MCP server by itself.

On macOS and Linux, resolve setup scripts relative to this skill file:

• `../../scripts/check-prereqs.sh`
• `../../scripts/set-env.sh`

When the host exposes a plugin-root variable such as `CLAUDE_PLUGIN_ROOT`, using `$CLAUDE_PLUGIN_ROOT/scripts/...` is also valid. Do not assume the current shell directory is the plugin root.

On Windows, use `../../scripts/set-env.ps1 -Target <claude|codex|openclaw>` for every target. Use the matching PowerShell prerequisite checker. Both helpers require uv/uvx and the selected client's CLI (`claude`, `codex` or `openclaw`). A working Python 3.11+ on PATH is used first; otherwise uv supplies managed Python (with a possible first-run download). No separate Python installation is needed. Do not substitute direct client registration commands, which can expose env values in process arguments.

Step 0: Check Prerequisites

Before asking for credentials, run the prereq checker for the current OS.

On macOS/Linux:

bash <path-to-plugin>/scripts/check-prereqs.sh --target <claude|codex|openclaw> "unifi-network"

On Windows PowerShell:

powershell -ExecutionPolicy Bypass -File <path-to-plugin>/scripts/check-prereqs.ps1 -Target <claude|codex|openclaw> -PluginName "unifi-network"

If the script exits non-zero, stop and report the error. Do not proceed to credentials.

Step 1: Controller Host

Ask: "What is your UniFi controller's IP address or hostname?" Example: `192.168.1.1`.

Step 2: Credentials

Ask which authentication path the user needs:

• API key only for supported device, client, network, and WLAN inventory plus

API-key-only Integration API lookups

• Local username and password for legacy and session-backed tool families
• Both for the widest tool coverage and independently usable API-key reads if

the session fails

Ask for the local username when session authentication is selected. Never ask the user to send a password or API key in chat, and never place a raw secret in a tool call or command argument. Ask for exactly one indirect provider per secret: `UNIFI_NETWORK_PASSWORD_FILE=<absolute-path>` or `UNIFI_NETWORK_PASSWORD_COMMAND=<absolute argv>`, and `UNIFI_NETWORK_API_KEY_FILE=<absolute-path>` or `UNIFI_NETWORK_API_KEY_COMMAND=<absolute argv>`. A command provider can call a Keychain, `pass`, or 1Password helper; it is not run through a shell and must not prompt. If no indirect provider already exists, explain how to create one outside the chat transcript or use a client-native masked secret UI, then wait. In Claude Code that UI is the plugin's options dialog (`/plugin`, then `unifi-network`, then Configure options): its password and API key fields are masked and stored in the system keychain.

All three servers apply the same precedence: non-empty `UNIFI_<PRODUCT>_*` values override shared `UNIFI_*` values; empty values count as unset. This applies to host, username and credentials even where bundled YAML defaults name different variables. Shared providers are fallback only. Multiple non-empty spellings (plain, `_FILE`, `_COMMAND`) at the selected level refuse startup.

The setup helper switches providers atomically: selecting one spelling removes its saved siblings at the same level while preserving unrelated settings. To remove an authentication path, pipe a JSON patch setting all three saved spellings to `null` (for example `UNIFI_NETWORK_PASSWORD`, `UNIFI_NETWORK_PASSWORD_FILE`, `UNIFI_NETWORK_PASSWORD_COMMAND`). Remove or override shared fallback settings deliberately too; deleting product settings alone can reactivate shared credentials. Inherited environment providers must also be corrected in the launcher. Never delete a working provider in a separate preparatory write.

Claude Code is the exception for a raw password or API key it holds in the system keychain: it cannot clear one through `claude plugin configure` or the options dialog. Setup therefore refuses, with nothing changed, any change that would clear it, such as selecting a `_FILE` or `_COMMAND` provider for that credential or a null deletion. The message names the variable and the choices: keep the saved secret, or run `claude plugin uninstall` and `claude plugin install` with the plugin id it names (usually `unifi-network@unifi-plugins`), then rerun setup with the provider and the options