UniFi MCP Server API Documentation

Table of Contents

• Overview
• Configuration
• Connecting to the cloud API and local gateways together
• Authentication
• Performance Tracking
• MCP Tools
• MCP Resources
• MCP Prompts
• A2A Endpoints
• A2A Error Handling
• Resource Error Handling
• Rate Limiting
• Examples

Overview

Operator usage

Objective

Prerequisites

• You know the target API mode and transport mode.
• You know whether you need read-only verification or a write-path review.
• You have the current phase docs open alongside this reference.

Procedure

1. Start with configuration and authentication to confirm the runtime assumptions.
2. Read the feature surface that matches the current deployment mode.
3. Cross-check any roadmap-dependent claims against SPEC.md, DEVELOPMENT_PLAN.md, and the phase runbooks.
4. Use the examples and endpoint listings to validate the intended behavior before changing production state.

Verification

• The documented endpoint or tool exists in the current implementation.
• The reference does not overstate future features as live.
• The operator can map the doc to an actual test or validation step.

Rollback

• If the API reference drifts from the implementation, restate the supported surface and move aspirational material back to roadmap docs.

Common failure modes

• Treating roadmap language as if it were an implemented guarantee.
• Skipping the phase docs and relying on the API reference alone.
• Confusing future transport or auth modes with currently shipped behavior.

Architecture

┌─────────────────┐
│  AI Application │
│  (Claude, etc.) │
└────────┬────────┘
         │ MCP Protocol
         │
┌────────▼────────┐
│   UniFi MCP     │
│     Server      │
└────────┬────────┘
         │ UniFi API
         │
┌────────▼────────┐
│  UniFi Network  │
│   Controller    │
└─────────────────┘

Key Features

• Device Management: List, configure, and monitor UniFi devices
• Network Configuration: Manage networks, VLANs, and subnets
• Client Information: Query connected clients and their status
• Firewall Rules: Create and manage firewall rules
• Site Management: Work with multiple UniFi sites
• Real-time Monitoring: Access device and network statistics
• Roadmap alignment: native Protect, Access, multi-controller, dry-run, RBAC, audit, metrics, A2A, and webhooks are defined in SPEC.md

Configuration

Environment Variables

Note: the table below includes both currently supported settings and planned controls that will become active as Phase 5 lands. | Variable | Description | Required | Default | |----------|-------------|----------|---------| | UNIFI_API_KEY | UniFi API Key (used for both Network and Site Manager APIs) | Yes | - | | UNIFI_API_TYPE | API type: cloud-ea, cloud-v1, or local | No | cloud-ea | | UNIFI_MIXED_MODE | Expose the cloud and local tool modules together, for a fleet whose registry holds both cloud controllers and local gateways. Without it the exposed modules follow the single UNIFI_API_TYPE, so local-only tools are missing on a cloud-typed server even when a local gateway is registered. Needs no UNIFI_LOCAL_HOST: the gateways come from the registry. See Connecting to the cloud API and local gateways together | No | false | | UNIFI_LOCAL_HOST | Local gateway hostname or IP (required when UNIFI_API_TYPE=local) | No* | - | | UNIFI_LOCAL_PORT | Local gateway port | No | 443 | | UNIFI_LOCAL_VERIFY_SSL | Verify the local gateway’s TLS certificate. Setting false logs a startup warning; prefer UNIFI_LOCAL_CA_FILE for self-signed certs | No | true | | UNIFI_LOCAL_CA_FILE | CA certificate (PEM) to verify the local gateway with, in place of the default roots. Checked at startup. Can be the console’s own self-signed certificate | No | - | | UNIFI_LOCAL_TLS_SERVER_NAME | Name to check the local gateway’s certificate against, and send as SNI, when it is not UNIFI_LOCAL_HOST. UniFi OS’s own certificate names unifi.local, not the console’s address | No | - | | UNIFI_CLOUD_API_URL | UniFi Cloud API base URL | No | https://api.ui.com | | UNIFI_DEFAULT_SITE | Default site ID | No | default | | UNIFI_RATE_LIMIT_REQUESTS | Max requests per rate limit period | No | 100 | | UNIFI_RATE_LIMIT_PERIOD | Rate limit period in seconds | No | 60 | | UNIFI_REQUEST_TIMEOUT | Request timeout in seconds | No | 30 | | UNIFI_MAX_RETRIES | Maximum retry attempts | No | 3 | | UNIFI_RETRY_BACKOFF_FACTOR | Exponential backoff factor between retries | No | 2.0 | | UNIFI_RETRY_TOTAL_TIMEOUT | Wall-clock budget in seconds for one request, including all retries and backoff waits | No | 60 | | UNIFI_PROFILE | Tool exposure profile: network, devices, security, system, minimal, protect. An unrecognised value logs a warning and falls back to all modules | No | unset | | UNIFI_READ_ONLY | Register only non-mutating tools. State-changing tools are not exposed to the client at all | No | false | | UNIFI_DRY_RUN | Change-safe mode: every tool with a dry_run parameter runs as a preview, and mutating tools without one are not registered | No | false | | UNIFI_AUDIT_LOG_ENABLED | Write an audit record for mutating operations | No | true | | UNIFI_AUDIT_LOG_PATH | Append-only audit log path. Relative paths resolve against the process working directory, which is not predictable under stdio transport — prefer an absolute path. The file is created mode 0600 | No | audit.log | | UNIFI_AUDIT_FAIL_CLOSED | Refuse a mutating tool call (and a read, with UNIFI_AUDIT_READS) when its audit record cannot be written. Set false only as break-glass | No | true | | UNIFI_AUDIT_READS | Also audit read tool calls: attempt and outcome records with the principal, tool, arguments and result, never the response payload | No | false | | UNIFI_AUDIT_CHAIN_KEY | HMAC key for the audit hash chain; without it the chain uses plain SHA-256, which detects edits but can be recomputed by anyone who can write the file | No | unset | | UNIFI_AUDIT_SIEM_TARGETS | Comma-separated SIEM destinations for stored audit records: syslog+tls://host:6514, https://host/path (signed webhook), otlp+https://collector:4318 (see SECURITY.md). Requires UNIFI_AUDIT_CHAIN_KEY | No | unset | | UNIFI_AUDIT_SIEM_WEBHOOK_SECRET | HMAC-SHA256 key signing webhook deliveries; required for https:// targets | With a webhook | unset | | UNIFI_AUDIT_SIEM_OTLP_HEADERS | Extra headers for OTLP targets, key=value,key=value | No | unset | | UNIFI_AUDIT_SIEM_CA_FILE | CA bundle used to verify SIEM targets | No | system roots | | UNIFI_AUDIT_SIEM_BUFFER_DIR | On-disk buffer for undelivered records | No | siem-buffer next to the audit log | | UNIFI_AUDIT_SIEM_BUFFER_MAX_MB | Most undelivered data kept per target; the oldest is dropped beyond it | No | 100 | | UNIFI_AUDIT_LOG_ROTATE_MB | Rotate the JSONL audit file at this size into <log>.<UTC time>Z files; the chain continues across them | No | unset (never rotate) | | UNIFI_AUDIT_RETENTION_DAYS | Archive and delete audit records older than this: Postgres with python -m src.fleet.cli audit-retention --confirm, rotated JSONL files with python -m src.utils.audit_retention LOG --confirm (see SECURITY.md) | No | unset (keep forever) | | UNIFI_AUDIT_ARCHIVE_DIR | Where retention writes its archives | No | audit-archive next to the audit log | | UNIFI_AUDIT_SIEM_ANCHOR_SECONDS | How often each chain’s head is sent to the SIEM as an anchor | No | 300 | | DATABASE_URL | Postgres URL of the fleet controller registry. When set, controllers come from Postgres instead of the UNIFI_* settings (needs the [fleet] extra and python -m src.fleet.cli migrate) | No | unset | | UNIFI_FLEET_CREDENTIAL_KEY | Encrypts the controller API keys stored in Postgres; required with DATABASE_URL | With DATABASE_URL | unset | | UNIFI_FLEET_REGISTRY_REFRESH_SECONDS | How often each server reloads the registry from Postgres | No | 30 | | UNIFI_FLEET_MAX_OPEN_CLIENTS | Most controller connections each server keeps open; least recently used idle ones are closed beyond this (controller state such as cached auth is kept) | No | 256 | | UNIFI_FLEET_EXPECTED_REPLICAS | How many processes (server replicas and workers) share each controller’s rate limit. While Redis is unavailable each falls back to UNIFI_RATE_LIMIT_REQUESTS divided by this (at least 1), so together they stay near the controller’s budget | No | 1 | | UNIFI_FLEET_FANOUT_CONCURRENCY | Most controllers one fleet_fanout call reaches at once | No | 20 | | UNIFI_FLEET_FANOUT_TIMEOUT_SECONDS | Default per-controller timeout of fleet_fanout | No | 15 | | UNIFI_FLEET_FANOUT_DEADLINE_SECONDS | Default overall deadline of fleet_fanout; controllers not done by then are reported as timed out | No | 60 | | UNIFI_FLEET_WORKER_HEALTH_SECONDS | Worker (python -m src.worker): how often each controller is health-checked | No | 60 | | UNIFI_FLEET_WORKER_SYNC_SECONDS | Worker: how often each controller’s sites and device inventory are refreshed | No | 900 | | UNIFI_FLEET_WORKER_CONCURRENCY | Worker: most controller jobs one worker runs at once | No | 20 | | UNIFI_FLEET_WORKER_LEASE_SECONDS | Worker: how long membership and controller leases last without renewal; a dead worker’s controllers move to the others after this | No | 30 | | UNIFI_FLEET_WORKER_DOWN_AFTER | Worker: consecutive failed health checks before a controller is down (earlier failures mark it degraded) | No | 3 | | MIGRATION_DATABASE_URL | Used by python -m src.fleet.cli migrate/status instead of DATABASE_URL, so the schema owner can differ from the server’s least-privilege role | No | unset | | UNIFI_STDIO_ROLE | Role of the local stdio caller: viewer, operator, admin or fleet-admin | No | fleet-admin | | UNIFI_METRICS_ENABLED | Enable Prometheus metrics server | No | false | | WEBHOOK_SECRET | HMAC-SHA256 key verifying X-UniFi-Signature on POST /webhooks/unifi; without it the receiver refuses every request | To receive webhooks | unset | | UNIFI_CACHE_ENABLED | Use the Redis read cache when Redis is configured; set false to bypass it | No | true | | REDIS_URL | Redis URL for the response cache; takes precedence over REDIS_HOST/PORT/DB/PASSWORD | No | unset | | REDIS_HOST / REDIS_PORT / REDIS_DB / REDIS_PASSWORD | Redis location for the response cache | No | localhost / 6379 / 0 / unset | | UNIFI_SITE_MANAGER_ENABLED | Enable Site Manager API multi-site tools | No | false | | MCP_SERVER_TRANSPORT | Transport: stdio, http, sse, streamable_http | No | stdio | | MCP_SERVER_HOST | Server bind address for http/sse/streamable_http | No | 127.0.0.1 | | MCP_SERVER_PORT | Server port (http/sse transports) | No | 3000 | | MCP_AUTH_MAX_FAILURES | Failed bearer-token checks (401) allowed per client address within MCP_AUTH_FAILURE_WINDOW_SECONDS on a network transport. Past that the address gets 429 with Retry-After on every route except /healthz until the window clears. 0 disables it. Behind a reverse proxy every client shares the proxy’s address unless uvicorn trusts its X-Forwarded-For (FORWARDED_ALLOW_IPS) | No | 10 | | MCP_AUTH_FAILURE_WINDOW_SECONDS | Sliding window for MCP_AUTH_MAX_FAILURES | No | 60 | | MCP_STATELESS_HTTP | Run the HTTP transports without MCP sessions so any replica can answer any request (ignored for stdio and SSE). select_controller is then refused: pass controller=<name> per call. The default (stateful) mode needs per-client sticky routing across replicas, keyed on something stable from initialize onward (see MULTI_CONTROLLER.md) | No | false | | MCP_AUTH_TOKEN | Bearer token required to call the server over a network transport; comma-separate for several. Write an entry as <role>:<token> (viewer, operator, admin, fleet-admin) to give it a role; a bare token is fleet-admin. A misspelled or wrong-case role (Viewer:, veiwer:) stops the server instead of becoming a fleet-admin token. http/sse/streamable_http refuse to start without it. Ignored for stdio | No | unset | | DEBUG | Register debug_api_request, an arbitrary GET or DELETE to any controller endpoint (destructive tier; never registered under UNIFI_READ_ONLY). Leave unset in production | No | unset | | LOG_LEVEL | Logging level: DEBUG, INFO, WARNING, ERROR | No | INFO | | LOG_API_REQUESTS | Log each controller API request | No | true | | UNIFI_CACHE_TTL | Accepted but not used: read-cache lifetimes are fixed per resource type (sites, networks and WLANs 5 min, devices 1 min, clients 30 s) | No | 300 | | UNIFI_BACKUP_DOWNLOAD_DIR | Directory download_backup writes into; the caller names only the file | No | . | | SUPERMEMORY_ENABLED | Enable the Supermemory integration for operator notes | No | false | | SUPERMEMORY_API_KEY | Supermemory API key | With SUPERMEMORY_ENABLED | unset |

• Required when UNIFI_API_TYPE=local.

Configuration File

unifi:
  api_key: your-api-key-here
  api_type: cloud  # or 'local'
  host: api.ui.com  # or gateway IP for local
  port: 443
  verify_ssl: true
  site: default
  rate_limit: 100
  timeout: 30
  max_retries: 3

mcp:
  server_port: 3000
  log_level: INFO

Connecting to the cloud API and local gateways together

1. One controller, from the environment

# Cloud
UNIFI_API_TYPE=cloud-ea
UNIFI_API_KEY=<key>

# or one local gateway
UNIFI_API_TYPE=local
UNIFI_LOCAL_HOST=192.0.2.1
UNIFI_API_KEY=<key>

2. Several controllers, from Postgres (fleet mode)

# A local gateway, with its own key
await mcp.call_tool("register_controller", {
    "name": "hq", "api_type": "local", "local_host": "192.0.2.1",
    "api_key": "<hq-key>", "labels": {"region": "west"}, "confirm": True,
})

# Another local gateway
await mcp.call_tool("register_controller", {
    "name": "branch-017", "api_type": "local", "local_host": "192.0.2.17",
    "api_key": "<branch-key>", "confirm": True,
})

# A cloud controller sharing one Site Manager key
await mcp.call_tool("register_cloud_account", {
    "name": "corp", "api_key": "<cloud-key>", "confirm": True,
})
await mcp.call_tool("register_controller", {
    "name": "cloud-east", "api_type": "cloud-ea",
    "cloud_account": "corp", "confirm": True,
})

3. Mixed cloud and local, in one server

UNIFI_API_TYPE=cloud-ea          # the base stays cloud-shaped
UNIFI_MIXED_MODE=true            # expose cloud AND local tools
UNIFI_API_KEY=<cloud-key>
DATABASE_URL=postgresql://...    # the gateways come from the registry
UNIFI_FLEET_CREDENTIAL_KEY=<key>

• the cloud and local tool modules are both registered, so a call routed to a cloud controller reaches the cloud tools and a call routed to a local gateway reaches the local ones;
• no base UNIFI_LOCAL_HOST is needed — the gateways come from the registry;
• UNIFI_PROFILE still narrows the union, so UNIFI_PROFILE=protect in mixed mode exposes the Protect modules only;
• the start-up log names the mode and the module count, so the exposed surface is visible rather than inferred.

Limitations

• A tool must be registered to be reachable. A module outside the registered set cannot be called on any controller, whatever its type. This is what UNIFI_MIXED_MODE exists to fix.
• MCP resources always read the default controller. The sites:// family and friends take no controller argument; use the tools for a specific controller. Because they are built from the process-wide settings and cannot be routed, they stay gated on the base UNIFI_API_TYPE — mixed mode does not expose local resources on a cloud base.
• Tool modules are process-wide. A cloud-only call routed to a cloud controller still fails on a local-only endpoint, and the reverse, because the endpoint does not exist on that backend — mixed mode registers both sets, it does not make an endpoint appear on a controller that lacks it.
• One API type per registered controller. A controller entry is local, cloud-ea or cloud-v1; to reach the same hardware both ways, register it twice under different names.

Performance Tracking

Agnost.ai Integration (Optional)

Features

• Real-time Performance Metrics: Track tool execution times, success rates, and error patterns
• User Analytics: Monitor which tools are most frequently used and by whom
• Resource Access Patterns: Understand how MCP resources are accessed
• Error Tracking: Automatic error capture with stack traces and context
• Custom Event Tracking: Track specific business events (device adoptions, configuration changes)
• Dashboard: Visual analytics dashboard for performance insights

Configuration

# Enable performance tracking
AGNOST_ENABLED=true

# Agnost Organization ID (obtain from https://app.agnost.ai)
AGNOST_ORG_ID=your-organization-id-here

# Optional: Custom endpoint (defaults to https://api.agnost.ai)
AGNOST_ENDPOINT=https://api.agnost.ai

# Optional: Control what data is tracked
AGNOST_DISABLE_INPUT=false   # Set to true to disable input parameter tracking
AGNOST_DISABLE_OUTPUT=false  # Set to true to disable output/result tracking

Tracking Controls

• When false (default): Tool input parameters are tracked
• When true: Input parameters are excluded from tracking
• Use this to prevent sensitive configuration data from being sent

• When false (default): Tool results and outputs are tracked
• When true: Output data is excluded from tracking
• Use this to prevent sensitive response data from being sent

AGNOST_ENABLED=true
AGNOST_ORG_ID=your-org-id
AGNOST_DISABLE_INPUT=true   # Don't track input parameters
AGNOST_DISABLE_OUTPUT=true  # Don't track output data
# This configuration tracks only tool names, execution times, and success/failure

Tracked Metrics

• Tool name
• Input parameters (if disable_input=false)
• Output results (if disable_output=false)
• Execution time (milliseconds)
• Success/failure status
• Error messages (if any)

• Resource URI accessed
• Response data (if disable_output=false)
• Response size
• Access patterns

• Error type and message
• Stack trace and context
• Request metadata
• Frequency and patterns

• Average execution time per tool
• Tool usage frequency
• Peak usage times
• Success/failure rates

Privacy & Security

• Granular control via disable_input and disable_output flags
• Sensitive data (API keys, passwords) automatically masked in logs
• All data encrypted in transit (HTTPS)
• Opt-in only (disabled by default)

• Disable input tracking to prevent parameter exposure
• Disable output tracking to prevent response data exposure
• Complete opt-out by setting AGNOST_ENABLED=false
• No personally identifiable information (PII) collected by default

• GDPR compliant data handling
• Configurable data retention policies via agnost.ai dashboard
• Transparent data collection (documented in this API guide)
• Data encrypted in transit and at rest

Example Configurations

docker run -i \
  --name unifi-mcp \
  -e UNIFI_API_KEY=your-unifi-api-key \
  -e UNIFI_API_TYPE=cloud \
  -e AGNOST_ENABLED=true \
  -e AGNOST_ORG_ID=your-organization-id \
  ghcr.io/enuno/unifi-mcp-server:latest

{
  "mcpServers": {
    "unifi": {
      "command": "uv",
      "args": ["--directory", "/path/to/unifi-mcp-server", "run", "mcp", "run", "src/main.py"],
      "env": {
        "UNIFI_API_KEY": "your-api-key-here",
        "UNIFI_API_TYPE": "cloud",
        "AGNOST_ENABLED": "true",
        "AGNOST_ORG_ID": "your-org-id",
        "AGNOST_DISABLE_INPUT": "true",
        "AGNOST_DISABLE_OUTPUT": "true"
      }
    }
  }
}

AGNOST_ENABLED=true
AGNOST_ORG_ID=your-org-id
AGNOST_DISABLE_INPUT=true
AGNOST_DISABLE_OUTPUT=true
# Tracks only: tool names, execution times, success/failure rates

Viewing Analytics

• Real-time Performance Metrics: Tool execution times and latency
• Usage Trends: Most frequently used tools and resources
• Error Rates: Failure patterns and error types
• Performance Bottlenecks: Slowest operations and optimization opportunities
• Historical Data: Trends over time for capacity planning

MCP Toolbox Dashboard

# Start with Docker Compose
docker-compose up -d

# Access dashboard
open http://localhost:8080

• Real-time performance monitoring
• Visual analytics and graphs
• Error tracking and debugging
• Historical trend analysis
• Request/response inspection

Authentication

Obtaining Your API Key

1. Login to UniFi Site Manager
2. Navigate to Settings → Control Plane → Integrations
3. Create a new API Key by clicking “Create API Key”
4. Save the key immediately - it’s only displayed once!
5. Store the key securely in environment variables or secret management

Authentication Method

GET /v1/sites HTTP/1.1
Host: api.ui.com
X-API-Key: your-api-key-here
Accept: application/json

API Access Modes

• Base URL: https://api.ui.com/v1/
• Access cloud-hosted UniFi instances
• Requires internet connectivity
• SSL verification recommended

• Base URL: https://{gateway-ip}:{port}/proxy/network/integration
• Access local UniFi gateway directly
• Works without internet
• May require SSL verification disabled for self-signed certificates

Current Limitations

• Read-Only Access: The Early Access API is currently read-only. Write operations will be available in future API versions and will require manual key updates.
• Rate Limiting: See Rate Limiting section below

Security Considerations

• Never hardcode API keys in your code
• Store API keys in environment variables or secure secret management systems (AWS Secrets Manager, HashiCorp Vault, etc.)
• Use HTTPS when connecting to the UniFi API (especially for cloud)
• Implement proper access controls for MCP server access
• Rotate keys regularly - API keys can be regenerated from unifi.ui.com
• Monitor API key usage for suspicious activity
• Treat API keys like passwords - they provide full access to your UniFi environment

MCP Tools

Tool Categories

• Read-only Tools: Read-only operations for querying network information
• Mutating Tools: Mutating operations with safety mechanisms (confirm + dry-run)

Health Check

health_check

result = await mcp.call_tool("health_check", {})

{
  "status": "healthy",
  "version": "0.2.5",
  "api_type": "cloud"
}

Debug Passthrough

debug_api_request

• endpoint (string, required): controller-relative API path starting with a single /, e.g. /proxy/network/api/s/default/stat/device. Absolute (https://...) and scheme-relative (//host/...) URLs are refused, so the controller’s API key is never sent to another host
• method (string, optional): GET (default) or DELETE; anything else is refused
• confirm (boolean, optional): must be true for a DELETE unless dry_run is set
• dry_run (boolean, optional): return the request instead of sending it

result = await mcp.call_tool("debug_api_request", {"endpoint": "/proxy/network/api/s/default/stat/device"})

Controller Selection

list_controllers

select_controller

get_active_controller

Fleet Registry Administration

register_controller

update_controller

register_cloud_account

rotate_fleet_credentials

Access control

create_api_token

list_api_tokens

revoke_api_token / update_api_token_role

search_audit_log

verify_audit_chain

export_audit_log

python -m src.fleet.cli migrate              # create or upgrade the schema
python -m src.fleet.cli status               # exit 1 if the schema is behind
python -m src.fleet.cli import --name hq     # register the UNIFI_* controller
python -m src.fleet.cli tokens create --name first-admin --role fleet-admin
python -m src.fleet.cli tokens list
python -m src.fleet.cli tokens revoke --name first-admin

Fleet-Wide Reads

fleet_health

{
  "controllers": [
    {
      "name": "branch-office",
      "api_type": "local",
      "health": "ok",
      "capabilities": {"network_version": "10.6.21"},
      "platform_compat": {
        "network_11_capable": false,
        "reason": "USG-gated: at least one USG gateway was seen in this controller's device inventory. ..."
      }
    }
  ],
  "counts": {"ok": 1},
  "total": 1
}

fleet_sites

fleet_inventory

// fleet_inventory(model="UDM", firmware_below="4.1")
{
  "devices": [
    {"controller": "store-017", "site_id": "88f7af54-...", "id": "a1b2...", "mac": "aa:bb:cc:00:11:22",
     "name": "Gateway", "model": "UDM-Pro", "firmware_version": "4.0.9", "state": "ONLINE",
     "synced_seconds_ago": 412.7}
  ],
  "total": 1, "offset": 0, "by_model": {"UDM-Pro": 1}
}

fleet_compare_versions

// fleet_compare_versions(model="U7PRO")
{
  "models": {
    "U7PRO": {
      "versions": ["8.0.10", "7.6.1"],
      "newest": "8.0.10",
      "controllers": {
        "hq": {"count": 2, "versions": ["8.0.10", "7.6.1"], "behind": false, "synced_seconds_ago": 120, "stale": false},
        "branch": {"count": 1, "versions": ["7.6.1"], "behind": true, "synced_seconds_ago": 95, "stale": false}
      },
      "data_as_of_seconds_ago": 120,
      "stale": false
    }
  },
  "controllers_compared": ["branch", "hq"],
  "total_devices": 3
}

fleet_compare_sites

// fleet_compare_sites(controllers=["hq", "branch"])
{
  "common_sites": ["default"],
  "unique_sites": {"hq": [], "branch": []},
  "by_controller": {
    "hq": [{"site_id": "s-hq", "short_name": "default", "name": "Head office", "synced_seconds_ago": 120, "stale": false}],
    "branch": [{"site_id": "s-br", "short_name": "default", "name": "Branch", "synced_seconds_ago": 95, "stale": false}]
  },
  "controller_sync_age": {"hq": 120, "branch": 95},
  "data_as_of_seconds_ago": 120,
  "stale": false,
  "controllers_compared": ["branch", "hq"],
  "total_sites": 2
}

fleet_fanout

// fleet_fanout(tool="get_application_info", labels={"region": "west"})
{
  "tool": "get_application_info",
  "results": {
    "store-001": {"ok": true, "data": {"application_version": "9.4.19"}},
    "store-007": {"ok": false, "error": "timed out after 15s"}
  },
  "succeeded": 1, "failed": 1, "elapsed_seconds": 15.02
}

Protect Phase 3 Tools

• protect://nvrs
• protect://nvrs/{nvr_id}
• protect://cameras
• protect://cameras/{camera_id}

Cameras

• list_protect_cameras(limit=None, offset=None)
• get_protect_camera(camera_id)

result = await mcp.call_tool("list_protect_cameras", {"limit": 10, "offset": 0})
camera = await mcp.call_tool("get_protect_camera", {"camera_id": "cam-1"})

NVRs

• list_protect_nvrs()
• get_protect_nvr(nvr_id)

result = await mcp.call_tool("list_protect_nvrs", {})
nvr = await mcp.call_tool("get_protect_nvr", {"nvr_id": "nvr-1"})

Devices, lights, sensors, and chimes

• list_protect_devices(limit=None, offset=None)
• get_protect_device(device_id)
• update_protect_device(device_id, ...)
• list_protect_lights(limit=None, offset=None)
• get_protect_light(light_id)
• update_protect_light(light_id, ...)
• list_protect_sensors(limit=None, offset=None)
• get_protect_sensor(sensor_id)
• update_protect_sensor(sensor_id, ...)
• list_protect_chimes(limit=None, offset=None)
• get_protect_chime(chime_id)
• update_protect_chime(chime_id, ...)
• list_protect_device_updates(limit=None, offset=None) for device subscription messages

device = await mcp.call_tool("get_protect_device", {"device_id": "device-1"})
updates = await mcp.call_tool("list_protect_device_updates", {})

Views and viewers

• get_protect_meta_info()
• list_protect_viewers(limit=None, offset=None)
• get_protect_viewer(viewer_id)
• update_protect_viewer(viewer_id, ...)
• list_protect_live_views(limit=None, offset=None)
• get_protect_live_view(live_view_id)
• create_protect_live_view(live_view)
• update_protect_live_view(live_view_id, ...)

meta = await mcp.call_tool("get_protect_meta_info", {})
viewers = await mcp.call_tool("list_protect_viewers", {})

Events and alarm webhooks

• list_protect_events(limit=None, offset=None)
• get_protect_subscribe_events(limit=None, offset=None) compatibility alias
• get_protect_event_messages(limit=None, offset=None) compatibility alias
• get_protect_subscribe_devices(limit=None, offset=None) compatibility alias
• get_protect_device_updates(limit=None, offset=None) compatibility alias
• send_protect_alarm_webhook(webhook_id, payload=None): webhook_id is the alarm’s webhook trigger ID, one path segment of letters, digits, ., _, ~, : and -

events = await mcp.call_tool("list_protect_events", {})
webhook = await mcp.call_tool(
    "send_protect_alarm_webhook",
    {"webhook_id": "webhook-1", "payload": {"event": "manual-trigger"}, "confirm": True},
)

Still planned / not yet exposed

Device Management Tools

get_device_details

• site_id (string, required): Site identifier
• device_id (string, required): Device integration-API UUID (the IDs returned by get_network_topology). A legacy _id ObjectId is also accepted.

result = await mcp.call_tool("get_device_details", {
    "site_id": "default",
    "device_id": "b12257d4-d910-3b09-bcf9-e842229ac697"
})

{
  "id": "b12257d4-d910-3b09-bcf9-e842229ac697",
  "name": "Living Room AP",
  "model": "U7-Pro-Wall",
  "mac_address": "aa:bb:cc:dd:ee:ff",
  "ip_address": "192.168.2.100",
  "state": "ONLINE",
  "supported": true,
  "firmware_version": "8.6.11.18870",
  "firmware_updatable": false,
  "features": {"accessPoint": {}},
  "interfaces": {
    "ports": [],
    "radios": [{"frequencyGHz": 5, "channelWidthMHz": 320, "channel": 53}]
  }
}

get_device_statistics

• site_id (string, required): Site identifier
• device_id (string, required): Device ID

result = await mcp.call_tool("get_device_statistics", {
    "site_id": "default",
    "device_id": "507f1f77bcf86cd799439011"
})

{
  "device_id": "507f1f77bcf86cd799439011",
  "uptime": 86400,
  "cpu": 15,
  "mem": 42,
  "tx_bytes": 1024000000,
  "rx_bytes": 2048000000,
  "bytes": 3072000000,
  "state": 1,
  "uplink_depth": 0
}

list_devices_by_type

• site_id (string, required): Site identifier
• device_type (string, required): Device type filter (uap, usw, ugw, udm, uxg, etc.)

result = await mcp.call_tool("list_devices_by_type", {
    "site_id": "default",
    "device_type": "uap"
})

search_devices

• site_id (string, required): Site identifier
• query (string, required): Search query string

result = await mcp.call_tool("search_devices", {
    "site_id": "default",
    "query": "office"
})

list_pending_devices

• site_id (string, required): Site identifier
• limit (integer, optional): Maximum number of devices to return
• offset (integer, optional): Number of devices to skip

result = await mcp.call_tool("list_pending_devices", {
    "site_id": "default"
})

[
  {
    "id": null,
    "name": null,
    "model": "U7PG2",
    "type": "uap",
    "mac": "74:83:c2:aa:bb:cc",
    "ip": "192.168.2.57",
    "state": 1,
    "adopted": false,
    "version": "6.6.77.15402"
  }
]

Client Management Tools

get_client_details

• site_id (string, required): Site identifier
• client_mac (string, required): Client MAC address

result = await mcp.call_tool("get_client_details", {
    "site_id": "default",
    "client_mac": "aa:bb:cc:dd:ee:01"
})

{
  "mac": "aa:bb:cc:dd:ee:01",
  "hostname": "laptop-001",
  "ip": "192.168.2.100",
  "is_wired": false,
  "signal": -45,
  "tx_bytes": 1024000,
  "rx_bytes": 2048000
}

get_client_statistics

• site_id (string, required): Site identifier
• client_mac (string, required): Client MAC address

result = await mcp.call_tool("get_client_statistics", {
    "site_id": "default",
    "client_mac": "aa:bb:cc:dd:ee:01"
})

{
  "mac": "aa:bb:cc:dd:ee:01",
  "tx_bytes": 1024000,
  "rx_bytes": 2048000,
  "tx_packets": 15000,
  "rx_packets": 20000,
  "tx_rate": 150000,
  "rx_rate": 200000,
  "signal": -45,
  "rssi": 55,
  "noise": -90,
  "uptime": 3600,
  "is_wired": false
}

list_active_clients

• site_id (string, required): Site identifier

result = await mcp.call_tool("list_active_clients", {
    "site_id": "default"
})

search_clients

• site_id (string, required): Site identifier
• query (string, required): Search query string

result = await mcp.call_tool("search_clients", {
    "site_id": "default",
    "query": "laptop"
})

Network Information Tools

get_network_details

• site_id (string, required): Site identifier
• network_id (string, required): Network ID

result = await mcp.call_tool("get_network_details", {
    "site_id": "default",
    "network_id": "507f191e810c19729de860ea"
})

{
  "id": "507f191e810c19729de860ea",
  "name": "LAN",
  "purpose": "corporate",
  "vlan_id": 1,
  "ip_subnet": "192.168.1.0/24",
  "dhcpd_enabled": true
}

list_vlans

• site_id (string, required): Site identifier

result = await mcp.call_tool("list_vlans", {
    "site_id": "default"
})

get_subnet_info

• site_id (string, required): Site identifier
• network_id (string, required): Network ID

result = await mcp.call_tool("get_subnet_info", {
    "site_id": "default",
    "network_id": "507f191e810c19729de860ea"
})

{
  "network_id": "507f191e810c19729de860ea",
  "name": "LAN",
  "ip_subnet": "192.168.1.0/24",
  "vlan_id": 1,
  "dhcpd_enabled": true,
  "dhcpd_start": "192.168.2.100",
  "dhcpd_stop": "192.168.1.254",
  "dhcpd_leasetime": 86400,
  "dhcpd_dns_1": "8.8.8.8",
  "dhcpd_dns_2": "8.8.4.4",
  "dhcpd_gateway": "192.168.2.1",
  "domain_name": "local"
}

get_network_statistics

• site_id (string, required): Site identifier

result = await mcp.call_tool("get_network_statistics", {
    "site_id": "default"
})

{
  "site_id": "default",
  "networks": [
    {
      "network_id": "507f191e810c19729de860ea",
      "name": "LAN",
      "vlan_id": 1,
      "client_count": 15,
      "total_tx_bytes": 10240000,
      "total_rx_bytes": 20480000,
      "total_bytes": 30720000
    }
  ]
}

WAN and Dynamic DNS Tools

list_wan_connections

• site_id (string, required): Site identifier

result = await mcp.call_tool("list_wan_connections", {
    "site_id": "default"
})
# A sparse controller response:
# [{"id": "<uuid-1>", "name": "Internet 1"},
#  {"id": "<uuid-2>", "name": "Internet 2"}]

list_dynamic_dns

• site_id (string, required): Site identifier

result = await mcp.call_tool("list_dynamic_dns", {
    "site_id": "default"
})

get_dynamic_dns

• dynamic_dns_id (string, required): Dynamic DNS record ID
• site_id (string, required): Site identifier

create_dynamic_dns

• site_id (string, required): Site identifier
• host_name (string, required): Hostname to update
• service (string, optional): Provider service name, default custom
• interface (string, optional): WAN interface identifier, default wan
• login (string, optional): Provider login or username
• password (string, optional): Provider password or token, sent as x_password
• server (string, optional): Provider server for custom configurations
• custom_service (string, optional): Custom provider protocol/service label
• options (array, optional): Provider-specific options
• confirm (boolean/string, required for execution): Set true to apply
• dry_run (boolean/string, optional): Preview without applying

result = await mcp.call_tool("create_dynamic_dns", {
    "site_id": "default",
    "host_name": "vpn.example.com",
    "service": "custom",
    "server": "updates.example.com",
    "custom_service": "dyndns",
    "login": "api-user",
    "password": "provider-token",
    "confirm": True
})

update_dynamic_dns

• dynamic_dns_id (string, required): Dynamic DNS record ID
• site_id (string, required): Site identifier
• host_name, service, interface, login, password, server, custom_service, options (optional): Fields to update
• confirm (boolean/string, required for execution): Set true to apply
• dry_run (boolean/string, optional): Preview without applying

delete_dynamic_dns

• dynamic_dns_id (string, required): Dynamic DNS record ID
• site_id (string, required): Site identifier
• confirm (boolean/string, required for execution): Set true to apply
• dry_run (boolean/string, optional): Preview without applying

Tagged MAC Tools

list_mac_tags

• site_id (string, required): Site identifier

get_mac_tag

• tag_id (string, required): Tag ID (24-hex ObjectId)
• site_id (string, required): Site identifier

create_mac_tag

• name (string, required): Tag display name
• macs (array, required): Device MAC addresses to assign (may be empty)
• site_id (string, required): Site identifier
• confirm (boolean/string, required for execution): Set true to apply
• dry_run (boolean/string, optional): Preview without applying

result = await mcp.call_tool("create_mac_tag", {
    "site_id": "default",
    "name": "Lobby APs",
    "macs": ["aa:bb:cc:dd:ee:01", "AA-BB-CC-DD-EE-02"],
    "confirm": True
})

update_mac_tag

• tag_id (string, required): Tag ID
• site_id (string, required): Site identifier
• name (string, optional): New display name
• macs (array, optional): Full replacement member list
• add_macs (array, optional): MACs to add
• remove_macs (array, optional): MACs to remove
• confirm (boolean/string, required for execution): Set true to apply
• dry_run (boolean/string, optional): Preview without applying

result = await mcp.call_tool("update_mac_tag", {
    "site_id": "default",
    "tag_id": "5f1e2d3c4b5a697886950413",
    "add_macs": ["aa:bb:cc:dd:ee:03"],
    "remove_macs": ["aa:bb:cc:dd:ee:01"],
    "dry_run": True
})

delete_mac_tag

• tag_id (string, required): Tag ID
• site_id (string, required): Site identifier
• confirm (boolean/string, required for execution): Set true to apply
• dry_run (boolean/string, optional): Preview without applying

Device Migration Tools

move_device_to_site

• site_id (string, required): Site the device is in now
• device_id (string, required): Device MAC or 24-hex device ID
• target_site (string, required): Destination site by short name (e.g. default), UI description, or 24-hex _id. A description shared by several sites is rejected as ambiguous.
• confirm (boolean/string, required for execution): Set true to apply
• dry_run (boolean/string, optional): Preview without applying

result = await mcp.call_tool("move_device_to_site", {
    "site_id": "default",
    "device_id": "aa:bb:cc:dd:ee:01",
    "target_site": "Branch Office",
    "dry_run": True
})

migrate_device

• site_id (string, required): Site the device is in now
• device_id (string, required): Device MAC or 24-hex device ID
• inform_url (string, required): http(s)://<host>[:port]/inform, e.g. http://controller.example.net:8080/inform. Other paths, credentials, query strings, and non-HTTP schemes are rejected.
• confirm (boolean/string, required for execution): Set true to apply
• dry_run (boolean/string, optional): Preview without applying

cancel_device_migration

• site_id (string, required): Site the device was migrated from
• device_id (string, required): Device MAC or 24-hex device ID
• confirm (boolean/string, required for execution): Set true to apply
• dry_run (boolean/string, optional): Preview without applying

Site Management Tools

get_site_details

• site_id (string, required): Site identifier

result = await mcp.call_tool("get_site_details", {
    "site_id": "default"
})

{
  "id": "default",
  "name": "Default Site",
  "desc": "Default site description"
}

list_all_sites

result = await mcp.call_tool("list_all_sites", {})

get_site_statistics

• site_id (string, required): Site identifier

result = await mcp.call_tool("get_site_statistics", {
    "site_id": "default"
})

{
  "site_id": "default",
  "devices": {
    "total": 25,
    "online": 24,
    "offline": 1,
    "access_points": 10,
    "switches": 8,
    "gateways": 7
  },
  "clients": {
    "total": 42,
    "wired": 15,
    "wireless": 27
  },
  "networks": {
    "total": 5
  },
  "bandwidth": {
    "total_tx_bytes": 102400000,
    "total_rx_bytes": 204800000,
    "total_bytes": 307200000
  }
}

Site Manager API Tools (v0.3.0+)

• Set UNIFI_SITE_MANAGER_ENABLED=true
• The same UNIFI_API_KEY is used for both Site Manager and Network APIs
• See Site Manager API Docs for more details

get_isp_metrics

• site_id (string, required): Site identifier

result = await mcp.call_tool("get_isp_metrics", {
    "site_id": "site-12345"
})

{
  "site_id": "site-12345",
  "isp_name": "Example ISP",
  "download_bandwidth_mbps": 500.0,
  "upload_bandwidth_mbps": 100.0,
  "latency_ms": 15.5,
  "jitter_ms": 2.1,
  "packet_loss_percent": 0.05,
  "timestamp": "2026-02-16T12:00:00Z"
}

query_isp_metrics

• site_id (string, optional): Site identifier (omit for all sites)
• start_time (string, optional): Start time in ISO format (e.g., “2026-02-01T00:00:00Z”)
• end_time (string, optional): End time in ISO format

result = await mcp.call_tool("query_isp_metrics", {
    "site_id": "site-12345",
    "start_time": "2026-02-01T00:00:00Z",
    "end_time": "2026-02-16T00:00:00Z"
})

list_sdwan_configs

result = await mcp.call_tool("list_sdwan_configs", {})

[
  {"id": "9304163b-680d-4de8-a7a0-7617e328911d", "name": "SD-WAN test", "type": "sdwan-hbsp"}
]

get_sdwan_config

• config_id (string, required): Configuration identifier

result = await mcp.call_tool("get_sdwan_config", {
    "config_id": "sdwan-001"
})

get_sdwan_config_status

• config_id (string, required): Configuration identifier

result = await mcp.call_tool("get_sdwan_config_status", {
    "config_id": "sdwan-001"
})

{
  "id": "",
  "fingerprint": "example-fingerprint",
  "generateStatus": "OK",
  "errors": [],
  "warnings": [],
  "hubs": [{"siteId": "site-hub", "applyStatus": "ok", "primaryWanStatus": {"latency": 1, "internetIssues": []}}],
  "spokes": [{"siteId": "site-spoke", "applyStatus": "ok", "connections": [{"hubId": "hub-1", "tunnels": [{"spokeWanId": "WAN", "hubWanId": "WAN", "status": "connected"}]}]}]
}

list_hosts

• limit (integer, optional): Maximum number of hosts to return
• offset (integer, optional): Number of hosts to skip (for pagination)

result = await mcp.call_tool("list_hosts", {
    "limit": 50,
    "offset": 0
})

[
  {
    "host_id": "host-001",
    "hostname": "unifi-controller-1",
    "ip_address": "192.168.1.10",
    "mac_address": "00:11:22:33:44:55",
    "model": "UDM-Pro",
    "version": "3.2.9",
    "site_count": 3,
    "status": "online",
    "last_seen": "2026-02-16T12:00:00Z"
  }
]

get_host

• host_id (string, required): Host identifier

result = await mcp.call_tool("get_host", {
    "host_id": "host-001"
})

get_version_control

result = await mcp.call_tool("get_version_control", {})

{
  "current_version": "1.0.0",
  "latest_version": "1.1.0",
  "deprecated_versions": ["0.9.0", "0.8.0"],
  "changelog_url": "https://developer.ui.com/site-manager-api/changelog",
  "upgrade_recommended": true,
  "min_supported_version": "1.0.0"
}

Cloud Connector passthrough tools

• console_id is the host ID from list_hosts, for example 70A7...8EC3:1093004219. Surrounding whitespace is stripped and the stripped value is what goes into the URL. What remains must be one path segment of letters, digits, ., _, ~, : and -, and cannot be only dots.
• path is the sub-path under the proxy prefix, for example api/s/default/stat/device. Leading slashes are stripped. Every segment uses the same character set as console_id and cannot be empty, . or ..; one trailing slash is allowed. The whole path is capped at 2048 characters. ?, #, % and \ are refused: on the get tools, pass query strings through params.

devices = await mcp.call_tool(
    "connector_network_get",
    {"console_id": "70A7...8EC3:1093004219", "path": "api/s/default/stat/device"},
)

Phase 4: Mutating Tools

Safety Mechanisms

1. Confirmation Required: Must pass confirm=True to execute
2. Dry Run Mode: Pass dry_run=True to preview without changes
3. Audit Logging: All operations logged to audit.log
4. Input Validation: Parameters validated before execution

Firewall Management

list_firewall_rules

create_firewall_rule

# Dry run first
result = await mcp.call_tool("create_firewall_rule", {
    "site_id": "default",
    "name": "Block SSH",
    "action": "drop",
    "protocol": "tcp",
    "port": 22,
    "dry_run": True
})

# Then execute
result = await mcp.call_tool("create_firewall_rule", {
    "site_id": "default",
    "name": "Block SSH",
    "action": "drop",
    "protocol": "tcp",
    "port": 22,
    "confirm": True
})

update_firewall_rule & delete_firewall_rule

Zone-Based Firewall (ZBF)

• ZBF is NOT available via Cloud API - requires local gateway API access (api_type='local')
• Tested on UniFi Express 7 and UDM Pro (API v10.0.156)
• Only 2 out of 15 implemented endpoints actually exist in the UniFi API

• list_firewall_zones - List all zones
• create_firewall_zone - Create new zone (untested but likely works)
• update_firewall_zone - Modify zone (untested but likely works)
• delete_firewall_zone - Delete zone (untested but likely works)
• assign_network_to_zone - Assign network to zone (untested but likely works)
• unassign_network_from_zone - Remove network from zone (untested but likely works)
• get_zone_networks - List networks in a zone

• ❌ Zone policy matrix operations (get/update/delete policies between zones)
• ❌ Application blocking per zone
• ❌ Zone traffic statistics
• These tools have been REMOVED - configure these features in UniFi Console UI

• Zones: Logical groups of networks (e.g., Internal, External, Gateway, VPN, Hotspot, DMZ)
• Network Assignment: Assign networks to zones for organization
• Zone-to-Zone Policies: Must be configured manually in UniFi Console UI
• Application Blocking: Use DPI categories at network level instead

Zone Management

list_firewall_zones

• site_id (string, required): Site identifier

zones = await mcp.call_tool("list_firewall_zones", {
    "site_id": "default"
})

[
  {
    "id": "zone-lan",
    "site_id": "default",
    "name": "LAN Zone",
    "description": "Corporate network",
    "network_ids": ["net-001", "net-002"]
  },
  {
    "id": "zone-guest",
    "site_id": "default",
    "name": "Guest Zone",
    "description": "Guest WiFi",
    "network_ids": ["net-guest-001"]
  }
]

create_firewall_zone

• site_id (string, required): Site identifier
• name (string, required): Zone name
• description (string, optional): Zone description
• network_ids (array, optional): Network IDs to assign
• confirm (boolean, required): Must be true
• dry_run (boolean, optional): Preview changes

# Dry run first
preview = await mcp.call_tool("create_firewall_zone", {
    "site_id": "default",
    "name": "IoT Zone",
    "description": "Internet of Things devices",
    "network_ids": ["net-iot-001"],
    "confirm": True,
    "dry_run": True
})

# Execute
zone = await mcp.call_tool("create_firewall_zone", {
    "site_id": "default",
    "name": "IoT Zone",
    "description": "Internet of Things devices",
    "network_ids": ["net-iot-001"],
    "confirm": True
})

update_firewall_zone

• site_id (string, required): Site identifier
• firewall_zone_id (string, required): Zone ID
• name (string, optional): New zone name
• description (string, optional): New description
• network_ids (array, optional): Updated network list
• confirm (boolean, required): Must be true
• dry_run (boolean, optional): Preview changes

delete_firewall_zone

• site_id (string, required): Site identifier
• zone_id (string, required): Zone ID to delete
• confirm (boolean, required): Must be true
• dry_run (boolean, optional): Preview changes

result = await mcp.call_tool("delete_firewall_zone", {
    "site_id": "default",
    "zone_id": "zone-old",
    "confirm": True
})

assign_network_to_zone

• site_id (string, required): Site identifier
• zone_id (string, required): Zone ID
• network_id (string, required): Network ID to assign
• confirm (boolean, required): Must be true
• dry_run (boolean, optional): Preview changes

result = await mcp.call_tool("assign_network_to_zone", {
    "site_id": "default",
    "zone_id": "zone-dmz",
    "network_id": "net-web-001",
    "confirm": True
})

unassign_network_from_zone

• site_id (string, required): Site identifier
• zone_id (string, required): Zone ID
• network_id (string, required): Network ID to remove
• confirm (boolean, required): Must be true
• dry_run (boolean, optional): Preview changes

get_zone_networks

• site_id (string, required): Site identifier
• zone_id (string, required): Zone ID

ZBF Usage Example

# Create a Guest zone
guest_zone = await mcp.call_tool("create_firewall_zone", {
    "site_id": "default",
    "name": "Guest",
    "description": "Guest WiFi network",
    "network_ids": ["net-guest"],
    "confirm": True
})

# Assign additional network to zone
await mcp.call_tool("assign_network_to_zone", {
    "site_id": "default",
    "zone_id": guest_zone["id"],
    "network_id": "net-guest-2",
    "confirm": True
})

# List all zones
zones = await mcp.call_tool("list_firewall_zones", {
    "site_id": "default"
})

# Get networks in a zone
networks = await mcp.call_tool("get_zone_networks", {
    "site_id": "default",
    "zone_id": guest_zone["id"]
})

• Zone-to-zone policies must be configured in UniFi Console UI
• Application blocking per zone is not available via API - use DPI categories at network level
• Zone traffic statistics are not available - use client statistics instead
• Always use dry_run=True to preview changes before applying
• See tests/verification/PHASE2_FINDINGS.md for complete verification details

Network Configuration

create_network

update_network & delete_network

update_site_to_site_vpn

Device Control

restart_device

locate_device

upgrade_device

Client Management

block_client & unblock_client

reconnect_client

MCP Prompts

A2A Endpoints

A2A Error Handling

• ConfirmationRequiredError: If confirm parameter not True
• ValidationError: If parameters invalid
• ResourceNotFoundError: If resource not found
• APIError: If UniFi API returns error

Phase 5: Enterprise scale and operational excellence

WiFi Network (SSID) Management

list_wlans

• site_id (string, required): Site identifier
• limit (integer, optional): Maximum number of WLANs to return
• offset (integer, optional): Number of WLANs to skip

result = await mcp.call_tool("list_wlans", {
    "site_id": "default",
    "limit": 10
})

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "name": "HomeWiFi",
    "security": "wpapsk",
    "enabled": true,
    "is_guest": false,
    "wpa_mode": "wpa2",
    "wpa_enc": "ccmp",
    "vlan": null,
    "hide_ssid": false
  }
]

create_wlan

• site_id (string, required): Site identifier
• name (string, required): SSID name
• security (string, required): Security type (open, wpapsk, wpaeap)
• password (string, optional): WiFi password (required for wpapsk)
• enabled (boolean, optional): Enable the WLAN immediately (default: true)
• is_guest (boolean, optional): Mark as guest network (default: false)
• wpa_mode (string, optional): WPA mode (wpa, wpa2, wpa3) (default: wpa2)
• wpa_enc (string, optional): WPA encryption (tkip, ccmp, ccmp-tkip) (default: ccmp)
• vlan_id (integer, optional): VLAN ID for network isolation (1-4094)
• hide_ssid (boolean, optional): Hide SSID from broadcast (default: false)
• confirm (boolean, required): Confirmation flag (must be True)
• dry_run (boolean, optional): Preview without creating

# Create guest WiFi with VLAN isolation
result = await mcp.call_tool("create_wlan", {
    "site_id": "default",
    "name": "Guest WiFi",
    "security": "wpapsk",
    "password": "securepass123",
    "is_guest": true,
    "wpa_mode": "wpa2",
    "vlan_id": 100,
    "confirm": True
})

update_wlan

• site_id (string, required): Site identifier
• wlan_id (string, required): WLAN ID
• name (string, optional): New SSID name
• security (string, optional): New security type
• password (string, optional): New WiFi password
• enabled (boolean, optional): Enable/disable the WLAN
• is_guest (boolean, optional): Mark as guest network
• wpa_mode (string, optional): New WPA mode
• wpa_enc (string, optional): New WPA encryption
• vlan_id (integer, optional): New VLAN ID
• hide_ssid (boolean, optional): Hide/show SSID
• confirm (boolean, required): Confirmation flag
• dry_run (boolean, optional): Preview without updating

delete_wlan

• site_id (string, required): Site identifier
• wlan_id (string, required): WLAN ID
• confirm (boolean, required): Confirmation flag
• dry_run (boolean, optional): Preview without deleting

get_wlan_statistics

• site_id (string, required): Site identifier
• wlan_id (string, optional): Optional WLAN ID to filter statistics

result = await mcp.call_tool("get_wlan_statistics", {
    "site_id": "default"
})

{
  "site_id": "default",
  "wlans": [
    {
      "wlan_id": "507f1f77bcf86cd799439011",
      "name": "HomeWiFi",
      "enabled": true,
      "security": "wpapsk",
      "is_guest": false,
      "client_count": 12,
      "total_tx_bytes": 10240000000,
      "total_rx_bytes": 20480000000,
      "total_bytes": 30720000000
    }
  ]
}

Port Forwarding Management

list_port_forwards

• site_id (string, required): Site identifier
• limit (integer, optional): Maximum number of rules to return
• offset (integer, optional): Number of rules to skip

result = await mcp.call_tool("list_port_forwards", {
    "site_id": "default"
})

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Web Server",
    "dst_port": "80",
    "fwd": "192.168.2.100",
    "fwd_port": "8080",
    "proto": "tcp",
    "enabled": true,
    "log": false
  }
]

create_port_forward

• site_id (string, required): Site identifier
• name (string, required): Rule name/description
• dst_port (integer, required): Destination port (external/WAN port), 1-65535
• fwd_ip (string, required): Forward to IPv4 address (internal/LAN), dotted quad without leading zeros
• fwd_port (integer, required): Forward to port (internal)
• protocol (string, optional): Protocol (tcp, udp, tcp_udp) (default: tcp_udp)
• src (string, optional): Source restriction: any, an IPv4 address, or a CIDR network such as 203.0.113.0/24 (host bits are cleared, so 203.0.113.7/24 is sent as 203.0.113.0/24) (default: any)
• enabled (boolean, optional): Enable the rule immediately (default: true)
• log (boolean, optional): Enable logging for this rule (default: false)
• confirm (boolean, required): Confirmation flag
• dry_run (boolean, optional): Preview without creating

# Forward external port 8080 to internal server
result = await mcp.call_tool("create_port_forward", {
    "site_id": "default",
    "name": "Web Server",
    "dst_port": 8080,
    "fwd_ip": "192.168.2.100",
    "fwd_port": 80,
    "protocol": "tcp",
    "confirm": True
})

delete_port_forward

• site_id (string, required): Site identifier
• rule_id (string, required): Port forwarding rule ID
• confirm (boolean, required): Confirmation flag
• dry_run (boolean, optional): Preview without deleting

Diagnostics and Historical Statistics

get_speed_test_history

• site_id (string, required): Site identifier
• hours (integer, optional): How far back to look (default: 168 = 7 days)

{
  "results": [
    {
      "id": "st-1",
      "download_speed_mbps": 935.0,
      "upload_speed_mbps": 918.0,
      "ping_ms": 12,
      "timestamp": "2026-10-22T03:00:00+00:00"
    }
  ]
}

get_historical_stats

• site_id (string, required): Site identifier
• subject (string, optional): site, ap, user, or gw (default: ap)
• interval (string, optional): 5minutes, hourly, daily, or monthly (default: hourly)
• hours (integer, optional): Window ending now, 1-2160 (default: 24)
• macs (string or array, optional): Restrict to specific devices/clients
• attrs (array, optional): Report attributes; defaults per subject, time always included

The statistics reset note. UniFi Network 11 replaces the statistics engine and resets historical data, so an empty history immediately after the upgrade is expected — not evidence of an outage or a broken tool (DEVELOPMENT_PLAN.md §4 Phase 8, N3). Every empty response from get_historical_stats, get_speed_test_history, get_dpi_statistics, list_top_applications and get_client_dpi carries a statistics_note field saying so. The field is absent on non-empty responses.

DPI (Deep Packet Inspection) Statistics

get_dpi_statistics

• site_id (string, required): Site identifier

result = await mcp.call_tool("get_dpi_statistics", {
    "site_id": "default"
})

{
  "site_id": "default",
  "applications": [
    {
      "app": 194,
      "cat": 4,
      "tx_bytes": 5120000000,
      "rx_bytes": 10240000000,
      "total_bytes": 15360000000
    }
  ],
  "categories": [
    {
      "cat": 4,
      "tx_bytes": 7680000000,
      "rx_bytes": 17920000000,
      "total_bytes": 25600000000
    }
  ],
  "total_applications": 15,
  "total_categories": 6
}

list_top_applications

• site_id (string, required): Site identifier
• limit (integer, optional): Number of top applications to return (default: 10)

result = await mcp.call_tool("list_top_applications", {
    "site_id": "default",
    "limit": 5
})

{
  "applications": [
    {
      "app": 194,
      "cat": 4,
      "tx_bytes": 5120000000,
      "rx_bytes": 10240000000,
      "total_bytes": 15360000000
    }
  ]
}

list_dpi_categories

result = await mcp.call_tool("list_dpi_categories", {})
# [{"id": 0, "name": "Instant messengers"}, {"id": 1, "name": "File transfer"}]

list_dpi_applications

• limit (integer, optional): Maximum number of results
• offset (integer, optional): Starting position
• filter_expr (string, optional): Filter expression

result = await mcp.call_tool("list_dpi_applications", {"limit": 2})
# [{"id": 3, "name": "ICQ"}, {"id": 7, "name": "Skype"}]

get_client_dpi

• site_id (string, required): Site identifier
• client_mac (string, required): Client MAC address
• time_range (string, optional): Time range for statistics (default: 24h)
• limit (integer, optional): Maximum number of applications to return
• offset (integer, optional): Number of applications to skip

result = await mcp.call_tool("get_client_dpi", {
    "site_id": "default",
    "client_mac": "aa:bb:cc:dd:ee:01",
    "time_range": "24h"
})

{
  "site_id": "default",
  "client_mac": "aa:bb:cc:dd:ee:01",
  "time_range": "24h",
  "total_tx_bytes": 512000000,
  "total_rx_bytes": 1024000000,
  "total_bytes": 1536000000,
  "applications": [
    {
      "application": "Netflix",
      "category": "Streaming",
      "tx_bytes": 256000000,
      "rx_bytes": 768000000,
      "total_bytes": 1024000000,
      "percentage": 66.67
    }
  ],
  "total_applications": 8
}

Traffic Flow Monitoring

get_traffic_flows

• site_id (string, required): Site identifier
• source_mac (string, optional): Filter by source MAC address (case-insensitive)
• source_ip (string, optional): Filter by source IP address
• source_zone_name (string, optional): Filter by source firewall zone name
• source_network_name (string, optional): Filter by source VLAN display name
• destination_ip (string, optional): Filter by destination IP address
• destination_port (integer, optional): Filter by destination port
• destination_zone_name (string, optional): Filter by destination zone name (useful for External)
• destination_network_name (string, optional): Filter by destination VLAN display name
• protocol (string, optional): Filter by protocol (TCP, UDP, ICMP, …)
• action (string, optional): Filter by firewall action (allowed, blocked)
• direction (string, optional): Filter by direction (outgoing, incoming, local)
• risk (string, optional): Filter by risk classification
• min_bytes (integer, optional): Only flows with at least this many total bytes
• client_name_contains (string, optional): Substring match against the source client name
• limit (integer, optional): Maximum number of flows to return (after filtering)
• hours (integer, optional): Page through the flows completed in the last hours (at least 1)
• max_flows (integer, optional): Upper bound on flows fetched in paged mode, before client-side filtering (1-50000, default 5000)

result = await mcp.call_tool("get_traffic_flows", {
    "site_id": "default",
    "source_mac": "aa:bb:cc:dd:ee:ff",
    "direction": "outgoing",
    "hours": 24
})

[
  {
    "flow_id": "flow_123abc",
    "site_id": "default",
    "source_ip": "192.168.2.100",
    "source_port": 50000,
    "destination_ip": "8.8.8.8",
    "destination_port": 443,
    "protocol": "tcp",
    "application_id": "app_https",
    "application_name": "HTTPS",
    "bytes_sent": 1024000,
    "bytes_received": 2048000,
    "packets_sent": 1000,
    "packets_received": 2000,
    "start_time": "2025-11-08T10:30:00Z",
    "end_time": null,
    "duration": null,
    "client_mac": "aa:bb:cc:dd:ee:ff",
    "device_id": "device_123"
  }
]

stream_traffic_flows

⚠️ NOT SUPPORTED — This tool raises NotImplementedError. The UniFi v2 traffic-flows endpoint returns a rolling snapshot of the 50 most-recent completed flows per call. It has no persistent connection, no pagination, and no server-push mechanism, so true streaming is not possible. Fast networks roll through the 50-flow window in under a second, making polling-based streaming impractical. Use instead: Poll get_traffic_flows on your own interval.

get_connection_states

⚠️ NOT SUPPORTED — This tool raises NotImplementedError. The UniFi v2 traffic-flows endpoint reports completed flows with start/end timestamps. It does not expose a live connection table or track in-progress connection states (active, closed, timed_out). Use instead: Use get_traffic_flows and inspect flow_start_time / flow_end_time fields to infer connection duration.

get_client_flow_aggregation

• site_id (string, required): Site identifier
• client_mac (string, required): Client MAC address
• hours (integer, optional): Aggregate the flows of the last hours instead of the latest-50 snapshot (see get_traffic_flows)
• max_flows (integer, optional): Upper bound on flows fetched in paged mode (1-50000, default 5000)

result = await mcp.call_tool("get_client_flow_aggregation", {
    "site_id": "default",
    "client_mac": "aa:bb:cc:dd:ee:ff",
    "hours": 24
})

{
  "client_mac": "aa:bb:cc:dd:ee:ff",
  "client_ip": "192.168.2.100",
  "site_id": "default",
  "total_flows": 1523,
  "total_bytes": 15360000000,
  "total_packets": 12000000,
  "active_flows": 45,
  "closed_flows": 1478,
  "auth_failures": 0,
  "top_applications": [
    {"application": "HTTPS", "bytes": 8589934592},
    {"application": "YouTube", "bytes": 4294967296}
  ],
  "top_destinations": [
    {"destination_ip": "8.8.8.8", "bytes": 2147483648}
  ]
}

block_flow_source_ip

• site_id (string, required): Site identifier
• flow_id (string, required): Flow identifier to block
• duration (string, optional): Block duration - “permanent” or “temporary” (default: permanent)
• expires_in_hours (integer, optional): Hours until expiration (for temporary blocks)
• confirm (boolean, required): Confirmation flag (must be true)
• dry_run (boolean, optional): Validate without executing (default: false)