ui-network-mcp

An MCP server for the UniFi Network API (integration API, version 11.0.97). The server uses FastMCP. The package on PyPI is ui-network-mcp. Ubiquiti publishes the API specification.

This is not an official Ubiquiti project.

Comparison with sirkirby/unifi-mcp

sirkirby/unifi-mcp is a larger MCP project for UniFi, with servers for UniFi Network, Protect, and Access. The two projects use different APIs and different credentials. Thus each project is useful for different tasks. The data about sirkirby/unifi-mcp is from November 2026.

Use this server if:

• You want to give the agent an API key, not an admin password. You can revoke an API key at any time, and a read-only key cannot change the network.
• You want a documented API. Ubiquiti publishes a specification for each version of the integration API. The private API has no public documentation and can change with a firmware update.
• You want remote access through the UniFi cloud connector, without a relay or another service.
• You want a server that is small enough to read and examine in full.
• You ask more questions about the network than you make changes to it.

Use sirkirby/unifi-mcp if:

• You use UniFi Protect or UniFi Access.
• You must change settings that the integration API does not have, for example port forwards, static routes, NAT rules, QoS rules, or VPN clients.
• You need history data, for example events, alarms, traffic statistics, DPI traffic, or traffic flows.

You can use both servers in the same MCP client. Give each server a different name in the MCP configuration.

Tools

Most tools are read-only. The server adds the write tools only if UNIFI_ALLOW_WRITES is true.

If a tool call does not include site_id, the server uses UNIFI_DEFAULT_SITE_ID. If that variable is not set and the console has exactly one site, the server uses that site.

The results do not show the WiFi passphrases. The server replaces each passphrase with ***REDACTED***, so that the passphrases do not get to the agent. The server does not hide the voucher codes, because you must give these codes to the guests.

Write tools

update_firewall_policy changes only the given fields. If the only changes are logging_enabled or report_flow_enabled, it sends a PATCH request. For all other changes, it reads the policy and sends the full policy with the changes. The server checks each policy body against typed models before it sends the request. The server does not send a request body that contains ***REDACTED***, because that body would replace a secret with the placeholder.

Caution: Examine each write tool call before you approve it. A wrong firewall policy can block the access to the console. remove_device resets an online device to the factory settings.

Configuration

Create an API key in UniFi Network, in Settings > Control Plane > Integrations. The server reads its settings from these environment variables:

Set exactly one of UNIFI_HOST, UNIFI_CONSOLE_ID, or UNIFI_BASE_URL.

Install the Claude Code plugin

The plugin adds the MCP server and four skills to Claude Code. The plugin needs uv. In Claude Code 2.1.275 or later, install the plugin with one command:

/plugin install unifi --marketplace henrik-dmg/ui-network-mcp

In an earlier version, add the marketplace first, and then install the plugin:

/plugin marketplace add henrik-dmg/ui-network-mcp
/plugin install unifi@ui-network-mcp

Claude Code then asks for the plugin options. The options are the same as the environment variables: the API key, one of the console host, the console ID, or the base URL, and the optional settings. Claude Code keeps the API key in the system keychain. To change the options later, run /plugin configure unifi@ui-network-mcp.

If you added the server before with claude mcp add unifi, remove that server with claude mcp remove unifi. Otherwise Claude Code has each tool two times.

Skills

Claude also uses a skill when your question matches it, for example "Is my network healthy?".

Add the server to Claude Code

If you do not want the plugin, you can add only the MCP server. You do not have to clone the repository. uvx installs the server from PyPI and starts it:

claude mcp add unifi \
  -e UNIFI_API_KEY=your-api-key \
  -e UNIFI_HOST=192.168.1.1 \
  -- uvx ui-network-mcp

For Claude Desktop and other MCP hosts, add this entry to the MCP configuration file:

{
  "mcpServers": {
    "unifi": {
      "command": "uvx",
      "args": ["ui-network-mcp"],
      "env": {
        "UNIFI_API_KEY": "your-api-key",
        "UNIFI_HOST": "192.168.1.1"
      }
    }
  }
}

To get a new version of the server, run uvx --refresh ui-network-mcp one time.

Run from a clone

To use a local clone, give its path to uv run --project:

claude mcp add unifi \
  -e UNIFI_API_KEY=your-api-key \
  -e UNIFI_HOST=192.168.1.1 \
  -- uv run --project /path/to/ui-network-mcp ui-network-mcp

uv run installs the clone in editable mode. Thus the server uses your changes to the code when it starts again, and you do not have to reinstall it.

Development

The project needs Python 3.14 and uv.

uv run pytest
uv run ruff check && uv run ruff format

The API specification is not in the repository. Before you add a tool, download the specification into the repository root. Git ignores this file.

curl -o network_v11.0.97_openapi.json https://developer.ui.com/network/v11.0.97/openapi.json

The CI workflow runs the lint, the tests, the build, and the plugin checks for each push to main and each pull request.

Release

1. Run uv version <version>, for example uv version 0.2.0. This command changes pyproject.toml and uv.lock.
2. Set the same version in .claude-plugin/plugin.json.
3. Commit the change and push it to main.
4. Publish a GitHub release with the tag v<version>, for example gh release create v0.2.0 --generate-notes.

The release workflow then builds the package and publishes it to PyPI.

License

This project uses the MIT license. See LICENSE. UniFi and Ubiquiti are trademarks of Ubiquiti Inc.