Claude Desktop (.dxt)
The Desktop Extension bundle (.dxt) installs mcp-unifi into Claude Desktop from one file, configured through a built-in form instead of JSON. The bundle includes the server and its Python dependencies, but not a Python interpreter: its manifest launches python, which must be a Python 3.13 (the compiled packages are built for 3.13 exactly).
The bundle uses stdio transport: Claude Desktop spawns the server as a subprocess when the conversation starts and tears it down when the conversation ends. There is no long-running server to manage.
Install
Section titled “Install”- Open the GitHub releases page.
- Download
mcp-unifi-<version>.dxtfrom the latest release. - Double-click the file. Claude Desktop prompts you to install the extension.
- Approve the install. The extension appears in Settings → Extensions in Claude Desktop.
Configure
Section titled “Configure”Click the extension’s gear icon in Settings → Extensions to open the configuration form. Five fields from 0.29.0 (the 0.28.0 bundle has no Read-only field):
| Field | What it sets | Default |
|---|---|---|
| Stub Mode (sample data) | STUB_MODE. While on, every answer is made-up sample data, even with a host and key filled in. Turn it off to see your own network. |
On |
| Read-only (from 0.29.0) | MCP_UNIFI_READONLY. While on, Claude can look but not change anything: every tool that would make a change is hidden and refused. |
On |
| UniFi Host | UNIFI_HOST. IP or hostname (e.g. 192.168.1.1). Required when Stub Mode is off. |
(empty) |
| UniFi API Key | UNIFI_API_KEY. Local API key from the gateway. The bundle manifest marks this field sensitive. |
(empty) |
| Modules Enabled | MCP_UNIFI_MODULES_ENABLED. Comma-separated. Use network,protect,access to enable all three. |
network |
To get the API key, log into the gateway UI, go to Settings → Control Plane → Integrations, and click Create API Key.
If you fill in the host and key and leave Stub Mode on, the 0.29.0 bundle logs a warning at startup and every answer carries a line saying the data is simulated. The 0.28.0 bundle says nothing.
Verify
Section titled “Verify”Start a new conversation in Claude Desktop and ask: “list my UniFi devices”. Claude should select the list_devices tool and return a structured list. With Stub Mode on you’ll see three made-up devices (a gateway, an access point and a switch). With it off you’ll see your adopted gateways, APs, and switches.
If tools don’t appear, check Settings → Extensions for an enable toggle and confirm the extension is on.
Why .dxt over manual config
Section titled “Why .dxt over manual config”Where the bundle runs, compared to a hand-edited claude_desktop_config.json pointing at uvx, it:
- Needs no JSON editing. Settings are entered in the extension’s configuration form.
- Marks the API key field sensitive in its manifest, so the key is not something you paste into a plaintext config file.
- Sets
MCP_TRANSPORT=stdiofor you, so there is no transport setting to get wrong.
For macOS and Windows today, and whenever you’d rather hand-edit claude_desktop_config.json, see the Claude Desktop recipe.