Connect Claude Code to UniFi locally, verify the correct interface, and publish only the standalone HTTP service when remote application access is required
UniFi MCP provides separate servers for UniFi Network, Protect, and Access, along with a standalone HTTP API for applications that do not communicate through MCP. This guide starts with the official Claude Code plugin workflow, explains direct execution with uvx, and shows how to distinguish an MCP process from a tunnel-ready HTTP listener. After the local configuration works, we explain how to expose the independently running API server through a Localtonet HTTP tunnel. The separation matters because the default Claude Code integration does not automatically create a conventional local website or API port.
Understand the UniFi MCP components before installing them
UniFi MCP is an independent, community-maintained open-source project for connecting AI assistants and automation systems to UniFi environments. It is not an official Ubiquiti project. Its primary MCP servers target UniFi Network, UniFi Protect, and UniFi Access. Each server exposes product-specific functionality as MCP tools that a compatible client can discover and invoke.
The project also includes unifi-api-server, an independent HTTP service intended for applications that do not speak MCP. According to the project documentation, this API server provides typed REST resources, read-only GraphQL queries, Server-Sent Events streams, scoped API keys and administration, audit records, and action endpoints for supported controller operations. It shares underlying manager code with the MCP servers, but it does not proxy them and does not require the MCP servers to be running.
This distinction determines what can be exposed through a normal HTTP tunnel. Claude Code commonly launches an MCP server as a local subprocess using standard input and output. A process using that transport does not necessarily listen on a TCP port. Localtonet HTTP tunnels, by contrast, point to a local IP address and port. For that reason, we first configure Claude Code as documented, then treat the standalone UniFi API server as a separate remote-access target.
Choose Network, Protect, or Access
Install only the component needed for the work you intend to perform. This reduces unnecessary tool exposure and makes permission review easier. Compatibility can vary by UniFi product, controller, firmware, and available API surface, so check the current component documentation for your environment before enabling operational workflows.
| Component | Typical focus | Claude Code plugin |
|---|---|---|
| UniFi Network | Inventory, clients, Wi-Fi, routing, firewall policy, traffic, and controlled network configuration | unifi-network@unifi-plugins |
| UniFi Protect | Cameras, events, detections, recordings, devices, and incident investigation workflows | unifi-protect@unifi-plugins |
| UniFi Access | Doors, visitors, credentials, policies, devices, and activity records | unifi-access@unifi-plugins |
| Standalone API | REST, read-only GraphQL, SSE, scoped API access, audit records, and supported application actions | Runs independently rather than as a Claude Code plugin |
Do not place administrator credentials in shell history, source control, screenshots, or a public configuration file. Create or select an account whose controller permissions match the intended tasks. If a workflow only needs read access, do not grant mutation permissions. Review any proposed change before approval and keep the project’s confirmation and policy controls enabled unless you have a specific operational reason to change them.
Install UniFi MCP for Claude Code
The project recommends its Claude Code plugin marketplace because the plugin includes the MCP server, an agent skill, and a guided setup workflow. Run the following commands inside Claude Code rather than in a conventional operating-system shell.
Add the official UniFi MCP plugin marketplace
Register the project marketplace in Claude Code so that its Network, Protect, and Access plugins become available.
/plugin marketplace add sirkirby/unifi-mcpInstall the plugin for the required UniFi application
Install Network for network operations. Install Protect or Access instead, or in addition, only when those product areas are needed.
/plugin install unifi-network@unifi-plugins/plugin install unifi-protect@unifi-plugins
/plugin install unifi-access@unifi-pluginsRun the matching guided setup command
For Network, start the setup skill shown below. The plugin guides you through connecting to the controller and configuring permissions. Use the corresponding setup workflow supplied by the installed Protect or Access plugin when configuring those components.
/unifi-network:unifi-network-setupVerify discovery and a low-risk read operation
Restart or reload Claude Code if the guided setup requests it. Confirm that the installed server is available to the client, then begin with an inventory, status, or other read-only request appropriate to the selected product. Do not begin verification with a configuration change. If discovery or authentication fails, correct the local setup before attempting remote access.
Run a server directly with uvx when needed
The plugin path is the recommended Claude Code workflow, but the project also documents direct package execution with uvx. This can help with local diagnostics or with MCP clients that let you register a command directly. Run only the package that matches the UniFi application you need:
uvx unifi-network-mcp@latest
uvx unifi-protect-mcp@latest
uvx unifi-access-mcp@latest
Direct execution requires controller connection settings, including the UniFi host, username, and password. The project identifies UNIFI_HOST, UNIFI_USERNAME, and UNIFI_PASSWORD for this purpose. Supply real values through a protected process configuration or secret-management mechanism. Do not paste them into documentation, commit them to a repository, or include them in a Localtonet tunnel definition.
The documented direct commands do not, by themselves, establish a verified bind address or port in the evidence available for this article. A standard-input and standard-output MCP process cannot be exposed by pointing an HTTP tunnel at an assumed port. Use the standalone API server for ordinary REST, GraphQL, and SSE application access, or consult the current component documentation if you specifically need an optional MCP HTTP transport.
Start and verify the standalone UniFi API locally
Remote HTTP access should begin only after unifi-api-server works on the local network. The project publishes the API server through PyPI and a GHCR container image and identifies its apps/api/README.md as the operational reference for quick-start and deployment patterns.
The approved evidence for this draft does not establish the current installation command, container arguments, bind address, listening port, URL paths, or health-check procedure. We therefore do not reproduce guessed commands or assume a familiar port. Those details can change between releases and must be taken from the API README that corresponds to the version being deployed.
Local API verification checklist
Follow the official API quick start, then record the exact local address and port reported by the deployed service. Verify the documented health or API endpoint from a machine that is allowed to reach that listener. Confirm that authentication is enforced where required, that a narrowly scoped API key can access only its intended resources, and that read-only GraphQL behavior matches the project documentation.
If SSE is part of the intended integration, test a documented stream locally and verify that the consuming application handles a long-lived HTTP connection correctly. If supported controller actions will be enabled, test them separately with an account and API key scoped to the smallest practical permission set. A successful local response is the prerequisite for adding Localtonet. Tunneling cannot repair an API process that is stopped, bound incorrectly, blocked locally, or failing controller authentication.
A public URL increases the number of networks from which the service can be reached. Use the API server’s scoped API keys and administration controls, limit controller permissions, and expose only the listener intended for remote consumers. Never place controller credentials or Localtonet device tokens in a URL, example request, application log, or shared support transcript.
Expose the verified HTTP listener with Localtonet
Once the standalone API responds locally, a Localtonet HTTP tunnel can provide a public HTTPS address without inbound router port forwarding, firewall changes, VPN setup, or a public IP address. Our client on the device establishes an outbound connection to a Localtonet relay server. The HTTP tunnel then forwards requests from its public address to the local IP address and port where the API is listening.
Use the actual address and port confirmed during local verification. Do not substitute values from another installation or assume that the API uses a particular default. The available relay server or region must also be selected from the current dashboard rather than copied from an old tutorial.
Install and run our client on the API host
Install the Localtonet client on the device running the UniFi API server, or on a device that can reach its verified local listener. Keep the client running while remote access is needed.
Authenticate and select the correct device
Use the device-specific authentication token through the supported client and dashboard workflow. Treat the token as a secret. Do not paste it into application code, screenshots, or the API server configuration.
Select an available relay server
Choose a currently available server or region from the Localtonet dashboard. Availability can vary, so do not hardcode a server code from another environment.
Create an HTTP tunnel to the verified local target
Configure the HTTP tunnel with the local IP address and exact listening port established during API verification. Select the appropriate HTTP process type offered in the current dashboard. Generated, selected, and custom-domain choices serve the same content at a public HTTPS address, but custom-domain DNS requirements must be confirmed in current documentation.
Start the tunnel
Creating a tunnel does not make it active. Press Start and confirm that the selected Localtonet device remains connected and that the tunnel reports a running state.
Test the assigned public HTTPS address
Use the assigned public URL with the API server’s required authentication. Begin with the same low-risk endpoint verified locally. When remote access is no longer required, stop or delete the tunnel.
For current dashboard guidance, consult our Localtonet HTTP tunnel documentation. The public endpoint remains available only while the selected client is connected and the tunnel is running.
Troubleshoot the configuration by layer
Diagnose problems from the inside out. First confirm that the chosen MCP plugin can communicate with the controller locally. Next verify the standalone API directly on its local listener. Only after those checks succeed should you test the Localtonet public address.
| Symptom | Likely layer | What to verify |
|---|---|---|
| Claude Code cannot discover UniFi tools | MCP plugin configuration | Confirm the marketplace, installed plugin, guided setup, MCP registration, and local controller reachability. |
| The API does not respond locally | Standalone API deployment | Check the version-specific API README, process status, documented listener, controller settings, and local authentication. |
| Local API works but the public URL does not | Localtonet tunnel | Confirm the selected device is connected, the tunnel is started, and the local IP address and port exactly match the working listener. |
| The public endpoint responds with an authorization error | API authorization | Verify the API key, its scope, and the requested resource without weakening authentication or exposing credentials. |
Frequently asked questions
Can I expose the default Claude Code UniFi MCP process with an HTTP tunnel?
Not based solely on the default plugin or uvx command. A subprocess using standard input and output has no conventional local HTTP port to forward. Use a documented HTTP transport when explicitly configured, or use the independent unifi-api-server for application-oriented HTTP access.
Does the standalone API require the MCP servers?
No. The project describes the API server as an independent HTTP service. It shares core manager code with the MCP servers but does not proxy or require them.
Which port should I enter in the Localtonet HTTP tunnel?
Enter the exact port reported by the locally verified API deployment. This article does not assume a default because the approved project evidence does not establish one. Follow the API README for the deployed version and test the listener locally first.
Does creating a Localtonet tunnel start it automatically?
No. Creating the configuration and running it are separate lifecycle actions. Start the tunnel after configuration, and keep the selected Localtonet client connected. Stop or delete the tunnel when public access is no longer required.
Does Localtonet replace UniFi API authentication?
No. The tunnel provides network reachability to the selected local service. Keep the API server’s scoped keys, controller permissions, policy controls, and other applicable authorization mechanisms enabled.
Is UniFi MCP an official Ubiquiti project?
No. It is an independent, community-maintained open-source project. Review its current compatibility documentation before connecting it to a production UniFi environment.
Publish your verified UniFi API with Localtonet
After the standalone API works locally and its authentication is configured, create an HTTP tunnel to its verified IP address and port. Keep the public route active only while the selected client is connected and remote access is required.
Get Started Free →
