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 20+
• 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:

git clone https://github.com/owine/unifi-network-mcp.git
cd unifi-network-mcp
npm install
npm 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

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 — The most dangerous tools (e.g., unifi_remove_device, unifi_bulk_delete_vouchers) require an explicit confirm: true parameter that must be present for the call to succeed
• Dry-run support — All write tools accept an optional dryRun: true parameter that returns a preview of the HTTP request (method, path, body) without making any changes

Tools (74 total)

System (1)

Sites (1)

Devices (8)

Clients (4)

Networks (6)

WiFi (5)

Hotspot Vouchers (5)

Firewall Zones & Policies (13)

ACL Rules (7)

Switching (6)

DNS Policies (5)

Traffic Matching (5)

Supporting (8)

Development

npm run build        # Compile TypeScript
npm start            # Run the server
npm run typecheck    # Type-check without emitting
npm run lint         # ESLint
npm test             # Run all tests (vitest)

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