UniFi MCP for Claude Code: local setup and remote-access readiness
Start with the UniFi MCP project's guided Claude Code installation, verify a low-risk local operation, and understand what must be established before considering remote access. This guide separates a local MCP subprocess, an HTTP-based MCP service, and an independent application API. It covers the documented plugin entry point and deployment acceptance checks, not a release-specific remote HTTP installation. We explain where Localtonet fits without assuming an HTTP port, authentication mechanism, or streaming capability that has not been verified.
📋 What's in this guide
Choose the interface and UniFi component first
UniFi MCP is an independent, community-maintained open-source project, not an official Ubiquiti product. Its project website describes separate MCP servers for UniFi Network, Protect, and Access, an independent HTTP API for applications, and an optional Cloud Relay for remote MCP access. These are different deployment choices, not interchangeable names for the same endpoint.
Start with the consumer. Claude Code needs an MCP connection to discover and call tools. A conventional dashboard or script may instead need an application API. A public HTTPS URL does not resolve that distinction: the service behind the URL still has to implement the protocol the client expects.
Select only the product server you need
The UniFi MCP project overview identifies Network, Protect, and Access as separate stable MCP products. Choose according to the UniFi application involved, not simply the device on which the controller runs. Installing unnecessary servers increases the configuration and permission surface you must review.
| Product | Project-described focus | Initial validation goal |
|---|---|---|
| Network | Inventory, clients, routing, Wi-Fi, firewall policy, traffic, and controlled configuration | Read a limited inventory or status result without changing configuration. |
| Protect | Cameras, events, detections, recordings, and incident investigation | Verify access to only the camera or event information the operator needs. |
| Access | Doors, visitors, credentials, policies, devices, and activity records | Begin with an authorized read, not a door or credential mutation. |
Keep the independent API outside this installation
The project describes unifi-api-server as running independently of the MCP servers while sharing the unifi-core manager layer. Its advertised interfaces include typed REST reads, read-only GraphQL, supported REST actions, SSE streams, scoped API keys, and audit records. These capabilities explain when an application might choose it; they do not make it a directly interchangeable MCP server.
This guide does not install the API, bootstrap its administration, or publish it. Those tasks require their own release-specific procedure, including storage, credentials, health checks, upgrades, and recovery. Keeping that deployment separate avoids leaving an additional privileged service partially configured during a Claude Code installation.
Prepare the local environment and permissions
The local walkthrough assumes Claude Code is already installed, signed in, and able to use plugin marketplace commands. It begins at the UniFi plugin installation boundary. It does not install Claude Code itself or claim a tested combination of operating system, controller firmware, and UniFi MCP package release.
Before installing, establish the following:
- Controller reachability: the machine running the MCP server must be able to reach the intended UniFi controller through an authorized network route.
- Product selection: know whether the task belongs to Network, Protect, or Access. The concrete command sequence below uses Network.
- Dedicated credentials: prepare a UniFi account with the smallest permissions that support the intended task.
- Secret handling: identify where the setup workflow will store settings and ensure that location is not shared or committed to source control.
- Change control: choose a read-only acceptance task and decide who can approve any later state-changing operation.
- Version record: record the installed client, plugin, server, and controller versions for troubleshooting and upgrades.
The project explicitly says compatibility varies by product, controller, firmware, and exposed API surface. A successful login is therefore not proof that every advertised operation works in your deployment. Test the particular reads or changes you intend to use.
Do not use a broadly privileged administrator account merely to make initial setup easier. A read-only account, where supported and sufficient, limits the consequences of mistaken tool use. Keep passwords out of chat transcripts, screenshots, shell history, container images, and repository files.
Understand the documented execution alternatives
The project's installation overview presents Claude Code plugins as the default route with a server, skills, and guided setup. It also lists direct uvx, Docker, and pipx paths. Those are alternatives, not extra steps to perform after installing the plugin.
For direct package execution, the overview identifies UNIFI_HOST, UNIFI_USERNAME, and UNIFI_PASSWORD as controller connection settings. It shows uvx unifi-network-mcp@latest for Network, with equivalent Protect and Access package names. That command is not an HTTP startup recipe and does not establish a port, endpoint path, or public-client authentication method.
Avoid mixing execution paths during the first installation. If the plugin launches one server and you independently start another, you can end up diagnosing the wrong process or different configuration. Similarly, @latest is a moving package selection, not a reproducible version pin.
Install the Network plugin through Claude Code
The following three commands are the Network installation entry point published in the project's Claude Code installation instructions. Enter them inside Claude Code, not in an operating-system shell. They invoke the project's guided setup rather than replacing it with an undocumented static configuration file.
Add the project marketplace
Register the UniFi MCP repository as the plugin marketplace.
/plugin marketplace add sirkirby/unifi-mcpInstall the Network plugin
Install the product plugin used by this local walkthrough.
/plugin install unifi-network@unifi-pluginsRun the guided Network setup
Invoke the supplied setup skill and review its requested configuration changes before approving them.
/unifi-network:unifi-network-setupDuring guided setup, use the intended controller and dedicated account. Review where credentials are saved, which server command will run, and whether any permissions or exposure settings are changed. If the workflow requests a client reload, complete it before diagnosing missing tools.
The available primary instructions establish these commands but do not specify every prompt, operating-system dependency, or configuration-file location for every plugin release. Treat the installed setup skill as an interactive component, not a fixed transcript. If it cannot complete or asks for an unexplained privilege increase, stop and resolve that issue locally. Do not add a tunnel as a workaround.
Verify the local MCP session before using it
A plugin installation message proves only that installation completed. Acceptance requires a running server, successful MCP communication, controller access, and a correct result from the intended product.
Check discovery and a limited read
- Confirm that Claude Code recognizes the installed plugin and its MCP integration.
- Confirm that the server starts without a missing executable, dependency, or configuration error.
- Check that the client can initialize the MCP session and discover available functionality.
- Request one small, authorized read against the intended controller.
- Compare the result with the controller's own interface and confirm that no configuration changed.
A suitable initial request is:
Use the UniFi Network integration to retrieve a small read-only
inventory or status summary from the configured controller.
Do not create, update, delete, restart, or otherwise change anything.
Report any permission or connectivity error without attempting to
increase privileges.This wording is a testing instruction, not a technical security boundary. Controller permissions and server-side controls must still constrain what tools can do.
Separate protocol behavior from controller behavior
MCP uses protocol operations such as tools/list and tools/call for tool discovery and invocation. A discovery success demonstrates communication with the MCP server; it does not establish that every controller operation is authorized or supported.
If results differ between clients, record the client version, server version, negotiated protocol information, and actual response shape. Do not assume that a particular response field or tool count must appear. This guide does not prescribe the earlier article's content-mode variables or lazy/eager discovery settings because their precise behavior is not established by the supplied primary documentation.
Likewise, an idle command-based server may be waiting for MCP input rather than serving a web page. Do not open arbitrary ports or invent an HTTP path to test a standard-input integration. Use the MCP client that owns the session.
Treat remote HTTP as a separate deployment decision
The project overview describes an optional Cloud Relay path:
Remote MCP client
→ Worker gateway
→ outbound WebSocket
→ Relay sidecar
→ local MCP servers over HTTPAccording to the project's Cloud Relay overview, the Worker exposes an authenticated Cloudflare-hosted MCP endpoint, brokers locations, and is managed through an npm CLI. The LAN-side relay discovers configured local servers and maintains the outbound connection. Reads can fan out across locations, while writes require an explicit location target.
Those are architectural statements, not a complete deployment procedure. In particular, the authenticated Worker endpoint does not prove that a local MCP HTTP listener independently authenticates requests. Authentication at one hop must not be assumed at another.
The available primary material does not establish a complete, release-specific UniFi MCP HTTP startup command, bind address, port, endpoint path, and direct-listener authentication procedure. We therefore do not provide a guessed remote setup or claim that a release has been tested. The local plugin workflow above should remain local until those details are independently established.
What a complete remote deployment must establish
Before approving a future remote deployment, require a runbook containing all of the following. These are acceptance criteria, not implied UniFi MCP configuration options.
- The exact server release and installation artifact, plus the remote client's supported transport.
- The documented command or configuration that enables HTTP, including bind address, listening port, and endpoint path.
- The component responsible for authenticating remote callers, its credential provisioning process, and its revocation procedure.
- A local MCP initialization and discovery test using the intended client.
- A successful read-only tool call and a separate unauthorized-request rejection test.
- Any session-header, protocol-version, origin-validation, or streaming requirements applicable to that implementation.
- Startup supervision, restart behavior, upgrade rollback, and credential recovery procedures.
Test streaming explicitly when it is used
A successful ordinary HTTP response does not prove Server-Sent Events compatibility. If the selected MCP transport uses an SSE response, test it directly against the local listener first. Confirm that events arrive incrementally rather than only when the connection closes.
Repeat the same test through the proposed public route. Include an idle interval, an intentional disconnect, and reconnection using the client's supported behavior. Compare local and remote results. Check each HTTP layer for buffering or timeout behavior if they differ.
This is a deployment test requirement, not a blanket claim that every client, relay, or Localtonet route supports every MCP streaming implementation. Do not substitute a browser landing page or a successful REST request for a working remote MCP session.
Understand where a Localtonet HTTP tunnel fits
With Localtonet, our client establishes an outbound connection to a Localtonet relay and provides a public URL for a configured HTTP service. The device does not need inbound router port forwarding, a public IP address, or a VPN setup for that workflow. Use it only in environments where this exposure is authorized.
An HTTP tunnel targets an IP address and port reachable from the selected Localtonet client. It does not convert standard input and output into HTTP, implement MCP on behalf of a REST API, or create a missing application authentication layer.
For a future verified HTTP deployment, use our HTTP tunnel documentation for the dashboard configuration sequence. We do not reproduce a generalized setup sequence here as though it were a tested UniFi MCP procedure. The following product concepts are important when reviewing that configuration:
- Device: the selected device-specific token identifies the Localtonet client that must reach the service. Protect that token separately from controller and application credentials.
- Relay: choose an available server or region from the current dashboard rather than copying an old server code.
- Target: use the listener address and port verified from the client device's network context.
- Public address: HTTP process types include Random Sub Domain, Custom Sub Domain, and Custom Domain, subject to current availability. Check current documentation before giving a custom domain DNS settings.
- Lifecycle: creating a tunnel does not start it. It must be started with Start and is available only while the selected client is connected and the tunnel is running.
Loopback deserves particular attention. If a service binds to 127.0.0.1, another computer cannot reach it through that address. Containers can introduce a separate network namespace as well. Validate connectivity from the actual Localtonet client environment, not merely from a terminal somewhere on the LAN.
Public verification is separate from tunnel creation
After an independently documented deployment is ready, public acceptance should repeat the local MCP initialization, discovery, and read-only call through the assigned HTTPS address using the intended remote client. Verify that requests without valid application credentials are rejected before tools or sensitive data are exposed.
If streaming is required, perform the explicit streaming test described above through that same route. Record the client and server versions and the outcome rather than claiming universal compatibility. Stop or delete the tunnel when remote access is no longer required.
Make each authentication and authorization boundary explicit
The project's control and safety overview describes default mutation previews that wait for confirmation, policy gates that can disable create, update, or delete behavior globally or at server and category scope, and default redaction of known secret-bearing response values. These are useful controls, but they solve different problems from public-client authentication.
| Boundary | What is established | What not to assume |
|---|---|---|
| Controller account | The MCP service uses controller access to perform operations. | A dedicated account is automatically read-only or appropriately scoped. |
| Mutation controls | The project describes confirmation and policy gates. | A confirmation prompt authenticates an internet caller or replaces controller permissions. |
| Response redaction | The project describes redaction of known secret-bearing values. | Every sensitive infrastructure detail or every log entry is removed. |
| Cloud Relay Worker | The project describes an authenticated hosted MCP endpoint. | The same authentication automatically protects a directly exposed local listener. |
| Localtonet device and tunnel | Our platform supplies public reachability to the selected service while the tunnel runs. | The device token is the remote MCP client's application credential. |
For the local workflow, the main boundaries are workstation access, the MCP client and server configuration, and controller authorization. For direct public HTTP, an additional caller-authentication boundary is essential. It must belong to the verified application or an explicitly deployed and tested access-control layer. This guide does not establish a direct UniFi MCP HTTP authentication scheme.
Keep controllers private. Publishing an MCP service does not require publishing the controller management interface. Avoid using a broad proxy route that accidentally exposes administration, unrelated services, or sensitive endpoints alongside the intended integration.
Treat returned inventory, client identifiers, camera information, and access records as potentially sensitive even when passwords are redacted. Restrict who can run the client, inspect its transcript, or collect diagnostic output. Human approval of a mutation should include the target controller, proposed change, and expected impact.
Operate and troubleshoot from the inside out
Keep a short local runbook containing the product selection, installed versions, controller identity, credential owner, protected configuration location, accepted read-only test, and recovery contact. Do not include passwords in the runbook itself.
After upgrading a plugin, client, controller, or firmware, repeat the same acceptance test. Check the project repository's upgrade guidance before updating existing installations. Do not change credentials, transport settings, and package versions simultaneously unless necessary: doing so makes regressions harder to isolate.
| Symptom | First checks | Avoid |
|---|---|---|
| Plugin command is not recognized | Confirm Claude Code supports the plugin workflow and that commands are being entered inside Claude Code. | Running slash commands in the operating-system shell. |
| Plugin installed but server does not start | Inspect startup errors, executable availability, dependencies, and saved configuration. Reload if requested. | Creating a tunnel to fix a local process failure. |
| Server connects but tools fail | Check controller reachability, credentials, product permissions, and operation compatibility. | Immediately switching to an unrestricted administrator account. |
| Expected functionality is missing | Check the selected product, installed release, discovered tool descriptions, and account scope. | Assuming an undocumented discovery-mode setting will fix it. |
| Results look different across clients | Compare client/server versions, negotiated protocol details, and raw responses with secrets removed. | Applying unverified content-mode environment variables. |
| A running process has no HTTP port | Determine whether it is a command-based MCP subprocess. | Guessing a port or endpoint path. |
| A future HTTP route works locally but not publicly | Check the client device, target reachability, tunnel running state, endpoint path, and application authentication. | Removing authentication to make the public test pass. |
| Ordinary HTTP works but a stream stalls | Compare local and remote incremental delivery, idle behavior, timeouts, and reconnection. | Treating an HTTP success status as proof of SSE compatibility. |
Recovery and shutdown
If local behavior becomes unexpected, stop using the integration for changes and preserve sanitized error information. Restore the last known working configuration through your normal change-control process, then repeat the read-only test. Reinstallation should not be the first response to a permission or controller-connectivity problem.
If credentials may have leaked, revoke or rotate the affected credential at its issuing system. Restarting a process does not revoke a password or token. Remove exposed copies from shared logs and review who could have accessed them.
For any later remote deployment, stop the public route first when investigating an exposure concern. Then assess the service configuration and credentials. A stopped tunnel removes that route, but it does not undo earlier disclosure or disable other routes to the same application.
Frequently asked questions
Does local Claude Code use require a public tunnel?
No. A local command-based MCP integration can communicate through standard input and output while the server reaches the controller privately. Localtonet is unnecessary for that connection.
Does this guide configure remote UniFi MCP HTTP access?
No. It covers the documented local plugin entry point and remote-readiness criteria. A complete version-specific HTTP startup and authentication procedure is not established here, so no port, path, or tested remote release is claimed.
Does the Cloud Relay's authentication protect a directly tunneled listener?
Not by assumption. The project describes authentication at its Worker endpoint. A direct route to a local listener needs its own verified authentication boundary, and must be tested independently.
Is the independent API required for the plugin?
No. The project describes the API as an independent application interface. It is not part of the local Network plugin command sequence shown here and should not be installed merely to troubleshoot MCP discovery.
Does a successful HTTPS request prove MCP streaming works?
No. Test MCP initialization, discovery, and a read-only call with the intended client. If the transport uses SSE, also test incremental delivery, idle behavior, disconnects, and reconnection locally and through the public route.
Is UniFi MCP an official Ubiquiti product?
No. It is an independent community project. Validate the selected release against your UniFi application, controller, firmware, permissions, and intended operations before relying on it.
Keep local MCP local until remote access is ready
Begin with the guided plugin workflow and a restricted read-only test. When a separately documented HTTP deployment has passed authentication and protocol checks, our HTTP tunneling platform can provide its public route. Publish only the service you intend to expose, and stop the tunnel when access is no longer needed.
Get Started Free →
