UniFi Network MCP Server

An MCP (Model Context Protocol) server that exposes the UniFi Network Integration API as tools for Claude Code and other MCP clients. Provides 74 tools for managing sites, devices, clients, networks, WiFi, firewalls, ACLs, switching, DNS policies, hotspot vouchers, VPNs, and more.

Prerequisites

• Node.js 22.13+ or 24 (see engines in package.json)
• A UniFi Network console with the Integration API enabled
• An API key generated from your UniFi Network console

Setup

Quick start (npx)

Add to Claude Code with a single command — no clone or build needed:

claude mcp add-json unifi-network '{"command":"npx","args":["-y","@owine/unifi-network-mcp@latest"],"env":{"UNIFI_NETWORK_HOST":"192.168.1.1","UNIFI_NETWORK_API_KEY":"your-api-key","UNIFI_NETWORK_VERIFY_SSL":"false"}}' -s user

Use -s user for global availability across all projects, or -s project for the current project only.

From source

If you prefer to build locally, this project uses pnpm via Corepack — use pnpm install, not npm install, which ignores pnpm-lock.yaml and resolves different dependency versions:

git clone https://github.com/owine/unifi-network-mcp.git
cd unifi-network-mcp
corepack enable
pnpm install
pnpm run build

Then add to Claude Code:

claude mcp add-json unifi-network '{"command":"node","args":["/path/to/unifi-network-mcp/dist/index.js"],"env":{"UNIFI_NETWORK_HOST":"192.168.1.1","UNIFI_NETWORK_API_KEY":"your-api-key","UNIFI_NETWORK_VERIFY_SSL":"false"}}' -s user

Environment Variables

Variable	Required	Default	Description
UNIFI_NETWORK_HOST	Yes	—	IP or hostname of your UniFi Network console
UNIFI_NETWORK_API_KEY	Yes	—	API key from Network integration settings
UNIFI_NETWORK_VERIFY_SSL	No	true	Set to false to skip TLS certificate verification (needed for self-signed certs)
UNIFI_NETWORK_READ_ONLY	No	true	Set to false to enable write/mutating tools (read-only by default)

Manual Configuration

Alternatively, add to your ~/.claude.json under the top-level "mcpServers" key:

{
  "mcpServers": {
    "unifi-network": {
      "command": "npx",
      "args": ["-y", "@owine/unifi-network-mcp@latest"],
      "env": {
        "UNIFI_NETWORK_HOST": "192.168.1.1",
        "UNIFI_NETWORK_API_KEY": "your-api-key",
        "UNIFI_NETWORK_VERIFY_SSL": "false"
      }
    }
  }
}

Safety Features

This server provides layered safety controls for responsible operation:

• Tool annotations — Every tool declares readOnlyHint, destructiveHint, and idempotentHint so MCP clients (like Claude Code) can make informed confirmation decisions
• Read-only mode — Enabled by default. Only read operations (list, get) are registered. Set UNIFI_NETWORK_READ_ONLY=false to enable write/mutating tools
• Destructive tool warnings — Tools that delete or irreversibly modify resources have descriptions prefixed with DESTRUCTIVE: to clearly signal risk
• Confirmation parameter — Every tool marked DESTRUCTIVE: (all 10 of them, including unifi_remove_device and unifi_bulk_delete_vouchers) requires an explicit confirm: true parameter for the call to succeed
• Dry-run support — All 33 write tools accept an optional dryRun: true parameter that returns a preview of the HTTP request (method, path, body) without making any changes

Structured Output

58 of the 74 tools (all 41 read tools, plus the 17 write tools whose API responses return the affected resource) declare an MCP outputSchema and return structuredContent alongside the usual text content. Clients that understand structured output get typed, machine-readable results instead of parsing JSON out of a text blob.

The schemas live in src/utils/output-schemas.ts and are verified against UniFi Network API 10.5.43. They deliberately use a loose strategy: every non-key field is optional and nested objects use .passthrough(), so firmware- and hardware-specific fields flow through unchanged rather than being stripped or triggering a validation error. This keeps the contract stable across console versions and hardware models.

Tools (74 total)

System (1)

Tool	Description
unifi_get_info	Get UniFi Network application info — returns applicationVersion only

Sites (1)

Tool	Description
unifi_list_sites	List all sites available to the API key

Devices (8)

Tool	Description
unifi_list_devices	List all adopted devices at a site
unifi_get_device	Get a specific device by ID
unifi_get_device_statistics	Get latest statistics for a device
unifi_list_pending_devices	List devices pending adoption (global)
unifi_adopt_device	Adopt a pending device
unifi_remove_device	DESTRUCTIVE: Remove (unadopt) a device — may factory reset
unifi_restart_device	Restart a device
unifi_power_cycle_port	Power cycle a specific port (PoE restart)

Clients (4)

Tool	Description
unifi_list_clients	List all connected clients (wired, wireless, VPN) at a site
unifi_get_client	Get a specific client by ID
unifi_authorize_guest	Authorize a guest client on a hotspot network
unifi_unauthorize_guest	Unauthorize a guest client

Networks (6)

Tool	Description
unifi_list_networks	List all networks at a site
unifi_get_network	Get a specific network by ID
unifi_get_network_references	Get references to a network (WiFi, firewall zones, etc.)
unifi_create_network	Create a new network
unifi_update_network	Update an existing network
unifi_delete_network	DESTRUCTIVE: Delete a network — disconnects all clients

WiFi (5)

Tool	Description
unifi_list_wifi	List all WiFi broadcasts (SSIDs) at a site
unifi_get_wifi	Get a specific WiFi network by ID
unifi_create_wifi	Create a new WiFi network (SSID)
unifi_update_wifi	Update an existing WiFi network
unifi_delete_wifi	DESTRUCTIVE: Delete a WiFi network — disconnects all clients

Hotspot Vouchers (5)

Tool	Description
unifi_list_vouchers	List all hotspot vouchers at a site
unifi_get_voucher	Get a specific hotspot voucher by ID
unifi_create_voucher	Create hotspot vouchers
unifi_delete_voucher	DESTRUCTIVE: Delete a hotspot voucher
unifi_bulk_delete_vouchers	DESTRUCTIVE: Bulk delete vouchers matching a filter

Firewall Zones & Policies (13)

Tool	Description
unifi_list_firewall_zones	List all firewall zones at a site
unifi_get_firewall_zone	Get a specific firewall zone by ID
unifi_create_firewall_zone	Create a new custom firewall zone
unifi_update_firewall_zone	Update a firewall zone
unifi_delete_firewall_zone	DESTRUCTIVE: Delete a custom firewall zone
unifi_list_firewall_policies	List all firewall policies at a site
unifi_get_firewall_policy	Get a specific firewall policy by ID
unifi_create_firewall_policy	Create a new firewall policy
unifi_update_firewall_policy	Update a firewall policy
unifi_patch_firewall_policy	Partially update a firewall policy (e.g. toggle logging)
unifi_delete_firewall_policy	DESTRUCTIVE: Delete a firewall policy
unifi_get_firewall_policy_ordering	Get user-defined firewall policy ordering for a zone pair
unifi_reorder_firewall_policies	Reorder user-defined firewall policies for a zone pair

ACL Rules (7)

Tool	Description
unifi_list_acl_rules	List all ACL rules at a site
unifi_get_acl_rule	Get a specific ACL rule by ID
unifi_get_acl_rule_ordering	Get user-defined ACL rule ordering
unifi_create_acl_rule	Create a new ACL rule
unifi_update_acl_rule	Update an ACL rule
unifi_delete_acl_rule	DESTRUCTIVE: Delete an ACL rule
unifi_reorder_acl_rules	Reorder user-defined ACL rules

Switching (6)

Tool	Description
unifi_list_switch_stacks	List all Switch Stacks at a site
unifi_get_switch_stack	Get details of a specific Switch Stack
unifi_list_mc_lag_domains	List all MC-LAG (Multi-Chassis LAG) Domains at a site
unifi_get_mc_lag_domain	Get details of a specific MC-LAG Domain
unifi_list_lags	List all LAGs (Link Aggregation Groups) at a site
unifi_get_lag	Get details of a specific LAG

DNS Policies (5)

Tool	Description
unifi_list_dns_policies	List all DNS policies at a site
unifi_get_dns_policy	Get a specific DNS policy by ID
unifi_create_dns_policy	Create a new DNS policy
unifi_update_dns_policy	Update a DNS policy
unifi_delete_dns_policy	DESTRUCTIVE: Delete a DNS policy

Traffic Matching (5)

Tool	Description
unifi_list_traffic_matching_lists	List all traffic matching lists (port groups, IP groups)
unifi_get_traffic_matching_list	Get a specific traffic matching list by ID
unifi_create_traffic_matching_list	Create a new traffic matching list
unifi_update_traffic_matching_list	Update a traffic matching list
unifi_delete_traffic_matching_list	DESTRUCTIVE: Delete a traffic matching list

Supporting (8)

Tool	Description
unifi_list_wans	List all WAN interfaces at a site
unifi_list_vpn_tunnels	List all site-to-site VPN tunnels at a site
unifi_list_vpn_servers	List all VPN servers at a site
unifi_list_radius_profiles	List all RADIUS profiles at a site
unifi_list_device_tags	List all device tags at a site
unifi_list_dpi_categories	List all DPI categories for traffic identification
unifi_list_dpi_applications	List all DPI applications for traffic identification
unifi_list_countries	List all countries/regions for geo-based rules

Development

pnpm install           # Install dependencies
pnpm run build         # Compile TypeScript
pnpm start             # Run the server
pnpm run typecheck     # Type-check without emitting
pnpm run lint          # ESLint
pnpm run lint:fix      # ESLint with auto-fix
pnpm test              # Run all tests (vitest)
pnpm run test:watch    # Run tests in watch mode
pnpm run test:coverage # Run tests with coverage

Commit conventions

This project uses conventional commits and release-please for automated releases:

• feat: ... — new feature (minor version bump)
• fix: ... — bug fix (patch version bump)
• feat!: ... or BREAKING CHANGE: footer — breaking change (major version bump)
• chore:, docs:, ci:, etc. — no version bump

On push to main, release-please opens a Release PR that bumps the version and updates CHANGELOG.md. Merging that PR publishes to npm automatically.

To override the version number, add Release-As: x.x.x in the commit body:

git commit --allow-empty -m "chore: release 2.0.0" -m "Release-As: 2.0.0"

License

MIT