.env file in the directory where you run the server, pass them directly to docker run, or define them inside your MCP client’s server configuration block. This page documents every variable the server accepts, their defaults, and when you need each one.
Obtaining your API key
Before you configure anything else, you need a UniFi API key.1
Log in to UniFi Site Manager
Go to unifi.ui.com and sign in to your account.
2
Open Integrations
Navigate to Settings → Control Plane → Integrations.
3
Create an API key
Click Create API Key and give it a descriptive name.
4
Save the key immediately
The key is shown only once. Copy it and store it in a secure location before closing the dialog.
Complete .env example
Copy the block below into a.env file and fill in the values for your environment. Lines beginning with # are comments and can be left as-is or removed.
Required variables
string
required
Your UniFi API key, obtained from Settings → Control Plane → Integrations in the UniFi Site Manager. This key is sent as the
X-API-Key HTTP header on every request.string
required
Selects which API the server connects to. Accepted values:
local— Direct access to your UniFi gateway over your local network. Provides full read/write access to all features. Recommended.cloud-v1— UniFi stable v1 Cloud API. Limited to aggregate site statistics. Rate limit: 10,000 requests/minute.cloud-ea— UniFi Early Access Cloud API. Limited to aggregate site statistics. Rate limit: 100 requests/minute.
Local gateway variables
These variables are required whenUNIFI_API_TYPE=local. They tell the server how to reach your UniFi gateway on the local network.
string
required
The IP address or hostname of your UniFi gateway. Example:
192.168.2.1. This variable is required when using local mode — the server will refuse to start without it.number
default:"443"
The HTTPS port your UniFi gateway listens on. The default is
443 for most UniFi gateways. Must be between 1 and 65535.boolean
default:"true"
Whether to verify the gateway’s SSL certificate. UniFi gateways use self-signed certificates by default, so set this to
false unless you have installed a trusted certificate on your gateway.Cloud API variables
These variables apply whenUNIFI_API_TYPE=cloud-v1 or UNIFI_API_TYPE=cloud-ea.
string
default:"https://api.ui.com"
The base URL for the UniFi Cloud API. You should not need to change this unless Ubiquiti publishes a new endpoint.
string
default:"default"
The site ID to use when no site is specified in a tool call. For most single-site setups, leave this as
default.Redis caching variables
Redis caching is optional but recommended for busy networks. When Redis is available, the server caches API responses and automatically invalidates entries when you make configuration changes, reducing latency and API rate-limit consumption.string
default:"localhost"
Hostname or IP address of your Redis server. When using Docker Compose, set this to the service name (e.g.,
redis).number
default:"6379"
Port Redis is listening on.
number
default:"0"
Redis database index to use. Values range from 0 to 15 on a default Redis installation.
string
Password for Redis authentication. Leave unset if your Redis instance does not require a password.
Webhook variable
string
A secret string used to verify the HMAC signature on incoming webhook events from your UniFi controller. If you are not using the webhook feature, leave this unset.
Performance tracking variables
The server optionally integrates with agnost.ai to record MCP tool usage and performance metrics. All of these are disabled by default and no data is sent unless you explicitly enable the integration.boolean
default:"false"
Set to
true to enable performance tracking. Requires AGNOST_ORG_ID to be set.string
Your agnost.ai organization ID. Obtain this from your account at app.agnost.ai.
string
default:"https://api.agnost.ai"
The agnost.ai API endpoint. You should not need to change this.
boolean
default:"false"
Set to
true to prevent tool input parameters from being sent to agnost.ai.boolean
default:"false"
Set to
true to prevent tool output from being sent to agnost.ai.API mode comparison
Next steps
Install with pip or uv
Install the server as a Python package and start it from the command line.
Run with Docker
Use Docker or Docker Compose for a containerized deployment.