UniFi

You can manage your UniFi Network Controller with AI assistants through an MCP server that exposes read-only actions. This setup lets you query devices, networks, and statistics, check security posture, and export configurations using natural language commands without exposing sensitive write operations.

How to use

Connect your MCP client to the UniFi MCP Server you run locally or remotely. Use natural language prompts to ask for status, lists, and insights. For example, request a list of all devices, get details about a specific client, review firewall rules, or fetch network statistics. All requests are read-only and designed to help you monitor and understand your UniFi environment quickly.

How to install

# Using uvx (recommended)
uvx --from git+https://github.com/MidwestMountaineer/Unifi-MCP-Server.git unifi-mcp-server

# Or pip
pip install git+https://github.com/MidwestMountaineer/Unifi-MCP-Server.git

Configure your MCP client

{
  "mcpServers": {
    "unifi": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/MidwestMountaineer/Unifi-MCP-Server.git", "unifi-mcp-server"],
      "env": {
        "UNIFI_HOST": "192.168.1.1",
        "UNIFI_API_KEY": "your-api-key-here",
        "UNIFI_VERIFY_SSL": "false"
      }
    }
  }
}

Test

Test the connection by asking your AI assistant to list your UniFi devices or retrieve a quick health summary. For example, say: “List all my UniFi devices” to confirm the server is communicating with your controller.

Additional notes

If you run into SSL issues during setup, set UNIFI_VERIFY_SSL to false in your environment and try again. Ensure you provide the correct controller host and a valid API key with Read Only permissions for safe, read-only access.

Configuration

The following environment variables are used to configure the UniFi MCP Server. Required values are marked accordingly.

Troubleshooting

Connection refused: Verify UNIFI_HOST is correct and the controller is reachable from the MCP server host. 401 Unauthorized: Regenerate the API key with Read Only permissions. SSL errors: Set UNIFI_VERIFY_SSL=false to bypass SSL verification (only for trusted networks). Empty results: Double-check the site name via UNIFI_SITE and ensure the API key has sufficient read permissions.

Docker

Run the MCP server in a container by using the standard container workflow described in the project’s Docker instructions. This enables isolated, reproducible deployments and easy scaling.

Development

If you are contributing or testing locally, clone the repository, install the package in editable mode, and run the development tools. This enables you to run tests and use a development console to interact with the MCP server.

Notes on usage patterns

• Use read-only tools to inspect your environment without making changes. - Combine multiple queries to build a picture of network health, device status, and security posture. - Regularly rotate API keys and monitor permissions to maintain a secure read-only surface.

Security considerations

Only grant Read Only API keys for MCP server access. Restrict network access to trusted clients and monitor MCP activity for unusual query patterns.

Available tools

unifi_list_devices

List all registered devices in the controller and provide basic details such as type, name, and status.

unifi_get_device_details

Fetch detailed information for a specific device, including IP, model, and last seen.

unifi_list_clients

List all clients connected to the network with summary information.

unifi_get_client_details

Retrieve in-depth details for a specific client such as MAC, IP, and connection history.

unifi_list_networks

List configured networks within the UniFi controller.

unifi_get_network_details

Get detailed information about a specific network configuration.

unifi_list_wlans

List all WLANs configured on the controller.

unifi_get_wlan_details

Retrieve detailed settings for a specific WLAN.

unifi_list_firewall_rules

Show all firewall rules configured in the controller.

unifi_get_firewall_rule_details

Get full details for a particular firewall rule.

unifi_list_traffic_routes

List traffic routes (IP routing rules) in the controller.

unifi_get_route_details

Fetch details for a specific traffic route.

unifi_list_port_forwards

List configured port forwarding rules.

unifi_get_port_forward_details

Provide detailed information about a single port forward rule.

unifi_get_ips_status

Check the current IPs status from the controller.

unifi_get_network_stats

Return overall network statistics such as throughput and utilization.

unifi_get_system_health

Provide health information for the UniFi system and components.

unifi_get_client_stats

Return statistics for specific clients or devices.

unifi_get_device_stats

Return statistics for a specific device or group of devices.

unifi_get_top_clients

Show top clients by bandwidth or usage.

unifi_get_dpi_stats

Provide DPI-related statistics and insights.

unifi_get_alerts

List current alerts and issues detected in the network.

unifi_get_dhcp_status

Check DHCP status and lease information.

unifi_verify_vlan_connectivity

Verify connectivity across VLANs as configured in the controller.

unifi_export_configuration

Export current controller configuration for backup or migration.