environment-setup— rules

<p align="center"> <img src="assets/unifi-mcp-server-logo.png" alt="UniFi MCP Server logo" width="200" height="200"> </p>

<h1 align="center">UniFi MCP Server</h1>

<p align="center"> <strong>AI-native control of UniFi networks through the Model Context Protocol</strong> </p>

<p align="center">

</p>

An MCP server that exposes UniFi Network, UniFi Protect and the UniFi cloud APIs (Site Manager, Mobility, InnerSpace, Carrier Fabric) as MCP tools, so AI agents can read and change UniFi infrastructure through one standard interface. It runs against one controller or, in fleet mode, many.

Current release: 0.6.4. See CHANGELOG.md for what changed.

Contents

• Features
• API modes
• Quick start
• Agent skills
• Tool profiles and safety controls
• Network transports and deployment
• Calling the server from code
• Documentation
• Development

Features

343 tools in local mode, from 60 modules.

• Network: clients (search, block, reconnect), networks and VLANs, WiFi SSIDs, DHCP reservations, DNS, WAN, guest vouchers, QoS profiles and traffic routes, DPI statistics, traffic flows.
• Devices: inventory, adoption, restart, locate, upgrade, radio settings, port profiles and per-port overrides, switching and stacks, topology export (JSON, GraphML, DOT), diagnostics, WiFi channel planning.
• Security: legacy firewall rules and groups, zone-based firewall (zones, policies, zone matrix), ACL rules, traffic matching lists, port forwarding, VPN and site-to-site VPN, content filtering, RADIUS and the guest portal.
• Protect: cameras, NVRs, views, events, sensors, lights, chimes, sirens, relays, speakers, alarm hubs and the alarm manager.
• Cloud: Site Manager (hosts, sites, cross-site statistics), the connector proxy, Mobility workspaces and devices, InnerSpace floor plans and inventory, Carrier Fabric subscribers and service plans.
• Operations: sites, backups (create, schedule, download, restore), events, multi-site aggregation, device migration between sites.
• Fleet mode (optional, with Postgres and Redis): many controllers behind one server, a controller registry with encrypted credentials, server-issued tokens with roles, a shared read cache, several replicas and background workers, and fleet_* tools that read across controllers. See MULTI_CONTROLLER.md and docs/FLEET_SCALING_PLAN.md.
• Safety: every mutating tool needs confirm=True and supports dry_run=True, plus read-only and dry-run server modes, role-based access over risk tiers, and a hash-chained audit log (see below).
• Observability: Prometheus /metrics, /healthz, SIEM export of audit records, optional Redis caching, webhooks with HMAC verification.

API modes

Set UNIFI_API_TYPE to choose how the server reaches UniFi.

The cloud tools (Site Manager, Mobility, InnerSpace, Carrier Fabric) call api.ui.com and are registered in every mode. Set UNIFI_SITE_MANAGER_ENABLED=true to use them. In local mode the server registers 343 tools; in either cloud mode, 71.

Zone-based firewall tools need UniFi Network 9.0 or later. Some documented UniFi endpoints do not exist on every firmware version; see docs/UNIFI_API.md.

Quick start

1. Get an API key

1. Sign in to UniFi Site Manager.
2. Go to Settings → Control Plane → Integrations and choose Create API Key.
3. Copy the key. It is shown only once.

2. Install

pip install unifi-mcp-server          # or: uv tool install unifi-mcp-server
# Fleet mode extras (Postgres, Redis):
pip install 'unifi-mcp-server[fleet]'

Or use the container image (amd64, arm64 and arm/v7; the -fleet variant for amd64 and arm64):

docker pull ghcr.io/enuno/unifi-mcp-server:latest

3. Add it to your MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows), Cursor (mcp.json, from View: Open MCP Settings) and most other MCP clients take the same mcpServers block:

{
  "mcpServers": {
    "unifi": {
      "command": "uvx",
      "args": ["unifi-mcp-server"],
      "env": {
        "UNIFI_API_KEY": "your-api-key-here",
        "UNIFI_API_TYPE": "local",
        "UNIFI_LOCAL_HOST": "192.168.2.1"
      }
    }
  }
}

If you installed with pip, use "command": "unifi-mcp-server" and drop args. To run the container instead:

{
  "mcpServers": {
    "unifi": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "UNIFI_API_KEY=your-api-key-here",
        "-e", "UNIFI_API_TYPE=local",
        "-e", "UNIFI_LOCAL_HOST=192.168.2.1",
        "ghcr.io/enuno/unifi-mcp-server:latest"
      ]
    }
  }
}

Keep -i and do not add -d: the client talks to the server over the container's stdin and stdout.

4. Main settings

.env.example lists every setting with comments, including audit logging, SIEM export, metrics, Supermemory and agnost.ai.

Agent skills

The skills/ directory holds agent skills: Markdown files an AI agent loads on demand, so it knows which UniFi tools exist and how to use them safely without keeping every tool definition in context. Each skill is a folder with a SKILL.md, in the layout Claude Code and other agents install.

Using the server (operator skills)

Changing this codebase (developer skills)

Install

Claude Code loads skills from ~/.claude/skills/<name>/SKILL.md (every session) or <project>/.claude/skills/<name>/SKILL.md (one project). Copy the folders you want:

git clone https://github.com/enuno/unifi-mcp-server.git
cd unifi-mcp-server
mkdir -p ~/.claude/skills

# All operator skills
cp -r skills/unifi-network skills/unifi-devices skills/unifi-security \
      skills/unifi-system skills/unifi-channel-planning ~/.claude/skills/

# Or one skill
cp -r skills/unifi-security ~/.claude/skills/

# The one-file overview of the whole server, as a skill named "unifi"
mkdir -p ~/.claude/skills/unifi && cp SKILL.md ~/.claude/skills/unifi/SKILL.md

Other agents that read the same SKILL.md format take the same folders; copy them into that agent's skills directory (Codex, for example, reads .agents/skills/). To update, pull and copy again. Inside this repository the developer skills are already installed for Claude Code (.claude/skills/) and Codex (.agents/skills/).

Use

You don't invoke a skill yourself. The agent reads each skill's description and loads the one that matches your request, then calls the MCP tools it describes, so the MCP server must also be configured in the same client. For example:

• "Which clients are on the guest VLAN right now?" loads unifi-network.
• "Audit the zone-based firewall for anything that allows WAN to LAN." loads unifi-security.
• "Which APs share a 5 GHz channel with a neighbor? Propose a channel plan." loads unifi-channel-planning.

If the agent doesn't pick a skill up, name it ("use the unifi-security skill"). Pair a skill with the matching UNIFI_PROFILE to keep the tool list small too. docs/SKILLS.md has the full guide.

Tool profiles and safety controls

Profiles. UNIFI_PROFILE registers only one group of modules, so the client sees fewer tool definitions:

Counts include the four fleet tools every profile gets. An unknown profile logs a warning and loads everything.

Safety controls.

• Every mutating tool requires confirm=True, and dry_run=True returns the change it would make without making it.
• UNIFI_READ_ONLY=true leaves mutating tools out of the tool list entirely. UNIFI_DRY_RUN=true forces every mutating call into preview mode.
• DEBUG=true adds debug_api_request, a raw GET or DELETE to any controller endpoint. It is a destructive-tier tool, a DELETE needs confirm=True, and read-only mode removes it. Leave DEBUG unset in production.
• With tokens, each tool has a risk tier (read, write, destructive) and each role a set of tiers: viewer reads, operator writes, and admin can also run destructive tools, including deletes, restores, restarts, client blocking and firewall policy changes. See API.md.
• Mutations are written to a hash-chained JSON-lines audit log (Postgres in fleet mode), with optional field encryption and SIEM export. See SECURITY.md.
• Inputs are validated with Pydantic, and credentials are redacted from logs.

Network transports and deployment

stdio is the default and needs no port. To serve MCP over the network, use Streamable HTTP:

export MCP_SERVER_TRANSPORT=streamable_http
export MCP_SERVER_PORT=3000
export MCP_AUTH_TOKEN=$(openssl rand -hex 32)   # required on every network transport
unifi-mcp-server
# Listening on 127.0.0.1:3000; clients send Authorization: Bearer $MCP_AUTH_TOKEN

Clients and MCP gateways then connect to http://<host>:3000/mcp. The server binds to 127.0.0.1 unless you set MCP_SERVER_HOST; put an authenticating TLS proxy in front before exposing it further. http also works. sse is deprecated: client proxies such as mcp-remote can race its initialize handshake (#96).

Container, with the published port on loopback:

services:
  unifi-mcp:
    image: ghcr.io/enuno/unifi-mcp-server:latest
    environment:
      UNIFI_API_KEY: your-api-key
      UNIFI_API_TYPE: local
      UNIFI_LOCAL_HOST: 192.168.2.1
      MCP_SERVER_TRANSPORT: streamable_http
      MCP_SERVER_PORT: 3000
      MCP_SERVER_HOST: 0.0.0.0          # inside the container only
      MCP_AUTH_TOKEN: ${MCP_AUTH_TOKEN}
    ports:
      - "127.0.0.1:3000:3000"

The repository's docker-compose.yml adds Redis and the MCP Toolbox dashboard (MCP_TOOLBOX.md); copy .env.docker.example to .env and run make compose-up. That example starts read-only (UNIFI_READ_ONLY=true) with a viewer stdio caller (UNIFI_STDIO_ROLE=viewer); to allow changes, set UNIFI_READ_ONLY=false and raise UNIFI_STDIO_ROLE to operator, or admin for destructive changes.

• Ansible: deploy/ansible/ deploys the server alone, a single-host fleet (server, worker, Redis, Postgres), or replicas behind nginx on several hosts. To have an AI agent run the deployment, start from a prompt in docs/deploy-prompts/.
• Kubernetes: deploy/helm/unifi-mcp/ is a Helm chart for the server alone or in fleet mode with workers, taking every credential from an existing Secret.

Calling the server from code

Any MCP client library works. With the FastMCP client:

import asyncio

from fastmcp import Client

config = {
    "mcpServers": {
        "unifi": {
            "command": "unifi-mcp-server",
            "env": {
                "UNIFI_API_KEY": "your-api-key-here",
                "UNIFI_API_TYPE": "local",
                "UNIFI_LOCAL_HOST": "192.168.2.1",
            },
        }
    }
}


async def main() -> None:
    async with Client(config) as client:
        sites = await client.call_tool("list_sites", {})
        print(sites.data)

        clients = await client.call_tool("list_active_clients", {"site_id": "default"})
        print(clients.data)

        # Mutations need confirm=True; dry_run=True previews the change.
        preview = await client.call_tool(
            "create_firewall_zone",
            {"site_id": "default", "name": "IoT", "confirm": True, "dry_run": True},
        )
        print(preview.data)


asyncio.run(main())

bin/unifi-cli runs a single tool from a shell (unifi-cli list-clients --site default); see docs/SKILLS.md.

Documentation

Development

git clone https://github.com/enuno/unifi-mcp-server.git
cd unifi-mcp-server
make install    # uv sync from uv.lock with the dev extra (no activation needed)
make hooks      # pre-commit and commit-msg hooks
cp .env.example .env   # then set UNIFI_API_KEY and, for local mode, UNIFI_LOCAL_HOST

make test       # unit tests
make ci         # every blocking CI check: lint, typecheck, security, docs coverage, tests with the 80% gate
make inspect    # open the server in the MCP Inspector (needs Node.js)
make help       # list every target

Without make, the same commands run through uv run --locked, for example uv run --locked pytest tests/unit/ -m "not integration". Integration tests (-m integration) need real UniFi hardware.

Layout: src/main.py builds the server, src/tools/ holds the tool modules, src/api/ the UniFi clients, src/models/ the Pydantic models, src/fleet/ the fleet stack, and tests/unit/ the unit tests. AGENTS.md and CLAUDE.md describe the conventions in detail, and commands.md lists the development commands.

Contributing

Contributions from people and AI coding agents are welcome. See CONTRIBUTING.md and AGENTS.md.

1. Fork the repository and create a branch.
2. Write tests first, keep new code at 80% coverage or better, and run make ci.
3. Use conventional commit messages (feat: ..., fix: ...) and open a pull request.

Issues with [Bug] in the title opened by a maintainer or collaborator get an automated first analysis; other reports are triaged by hand (details).

Security

Report vulnerabilities as described in SECURITY.md. Never commit credentials.

Acknowledgments

• sirkirby/unifi-network-mcp, the reference implementation
• MakeWithData's UniFi MCP guide
• Model Context Protocol and FastMCP

License

Apache License 2.0. See LICENSE.

Links

• Issues and discussions: GitHub Issues, GitHub Discussions
• Releases: <https://github.com/enuno/unifi-mcp-server/releases>
• PyPI: <https://pypi.org/project/unifi-mcp-server/>
• Container images: <https://ghcr.io/enuno/unifi-mcp-server>
• MCP Registry: search for io.github.enuno/unifi-mcp-server at <https://registry.modelcontextprotocol.io>