/unifi-access-setup

name: unifi-access-setup
description: Configure the UniFi Access MCP server for a supported MCP client — set controller host, credentials, API key, and permissions. Also use when the unifi-access 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 Access MCP Server

Walk the user through configuring their UniFi Access 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-access"

On Windows PowerShell:

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

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`.

If another UniFi MCP server is already configured, ask whether Access is on the same controller. Inspect a sanitized summary of the existing host and variable names only. Do not print full settings or raw `mcp list/get/show` output: these can contain stored credentials.

Step 2: Authentication

Access supports two auth paths:

• API key for the Access Developer API visitor family, including visitor reads,

creation, and deletion, plus tool families that accept either credential

• Local proxy session with username and password for local-only management tool

families and tool families that accept either credential

Ask whether the user wants API key only, username/password only, or both. Recommend both for the widest Access tool coverage.

For username/password, ask only for the local username. 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 selected secret: `UNIFI_ACCESS_PASSWORD_FILE=<absolute-path>` or `UNIFI_ACCESS_PASSWORD_COMMAND=<absolute argv>`, and `UNIFI_ACCESS_API_KEY_FILE=<absolute-path>` or `UNIFI_ACCESS_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-access`, 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_ACCESS_PASSWORD`, `UNIFI_ACCESS_PASSWORD_FILE`, `UNIFI_ACCESS_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