unifi-mcp-server: Skill for Claude Code

UniFi Cloud and Fleet Tools

Cloud tools call https://api.ui.com (Site Manager and the connector proxy). Fleet code lets one server serve many controllers. Read this before you change either. For the general add-a-tool workflow, see unifi-mcp-tool-builder.

Module map

Fleet tools are built inside functions, not defined at module level, so the "every public async function is a tool" rule does not apply to them:

API modes and gating

• APIType (src/config/config.py) is local, cloud-v1 or cloud-ea. The code default is cloud-ea.
• Cloud modes register only _CLOUD_TOOL_MODULES (src/main.py): sites, site_manager, connector, integration_api, carrier, innerspace and mobility. Local mode registers these too. In cloud mode get_site_statistics is left out, because its endpoints return 404 on the cloud API. That gives 71 tools, including the 4 fleet tools.
• Local mode registers both lists, so the cloud tools are available there too.
• Site Manager tools need UNIFI_SITE_MANAGER_ENABLED=true:
  • site_manager tools use the require_site_manager decorator;
  • mobility, innerspace and carrier call their own _require_cloud_api(), which checks site_manager_enabled;
  • the connector tools repeat the check inline.
• Paths:
  • SiteManagerClient (src/api/site_manager_client.py) uses the base URL https://api.ui.com/v1/ and the X-API-KEY header.
  • Connector calls go to connector/consoles/{console_id}/proxy/{network|protect}/{path}.
  • _validate_connector_params (src/tools/connector.py) checks both inputs before a client is built, and every connector tool uses the normalized values it returns. console_id goes through validate_path_segment (src/utils/validators.py): surrounding whitespace is stripped, then only [A-Za-z0-9._~:-] is allowed, up to 256 characters, and an all-dots value is refused. path goes through validate_proxy_path: leading slashes are stripped, every segment must match the same character set and must not be empty, . or .., a single trailing slash is allowed, and the whole path is capped at 2048 characters. ?, #, % and \ are refused, so query strings belong in params. This keeps a caller, including a viewer on the read-tier GET tools, inside the proxy prefix.
  • InnerSpace goes through the connector proxy.
  • settings.get_integration_path() gives /v1/... for cloud-v1 and /integration/v1/... for cloud-ea.
• Profiles: UNIFI_PROFILE has mobility, innerspace and carrier sets.