# unifi-local-mcp

A self-hosted [Model Context Protocol](https://modelcontextprotocol.io) server that gives
MCP clients such as Claude Code and Codex controlled access to the **official local
APIs** of UniFi applications (Network, Protect, Access). AI clients connect to this
server, never to UniFi. UniFi credentials never leave the server.

> **Status: Phase 1 (secure platform core), Phase 2 (UniFi Network) and Phase 3 (UniFi
> Protect) are complete; Phase 4 (UniFi Access) is in progress. The service serves MCP over Streamable HTTP and,
> through the stdio bridge, over stdio, is administered with the host-only `unifi-mcp`
> CLI, and implements all 73 documented UniFi Network operations
> ([docs/applications-network.md](docs/applications-network.md)), 73 of the 74 UniFi
> Protect 7.3.74 operations, including its event subscriptions
> ([docs/applications-protect.md](docs/applications-protect.md),
> [docs/events.md](docs/events.md)), and 97 of the 107 UniFi Access operations
> ([docs/applications-access.md](docs/applications-access.md)). All are tested against
> synthetic consoles; Network and Protect reads were also checked on a real console
> (Network 11.0.99, Protect 7.3.74). Access has not run on a real console.** See [docs/phase-checklist.md](docs/phase-checklist.md),
> [docs/installation.md](docs/installation.md) and [docs/administration.md](docs/administration.md).

## Design principles

- **Secure by default:** read-only, least privilege, deny by default. An immutable
  `UNIFI_MCP_FORCE_READ_ONLY` deployment lock is available.
- **Official local APIs only:** no cloud or Site Manager access, no undocumented endpoints,
  no raw HTTP proxy tools.
- **Independent human approval** for high-impact changes, via the admin UI or local CLI.
  An AI can never approve.
- **Per-client identity:** one revocable token per MCP client, with permission-filtered
  tool lists.
- Streamable HTTP and an authenticated stdio bridge; MCP 2026-07-28 and 2025-era clients.

## Repository map

| Path                                                   | Contents                                                                |
| ------------------------------------------------------ | ----------------------------------------------------------------------- |
| [`unifi-mcp-design-spec.md`](unifi-mcp-design-spec.md) | The design specification (source of truth)                              |
| [`docs/`](docs/index.md)                               | Manual, ADRs, threat model, API coverage                                |
| [`api-specs/`](api-specs/README.md)                    | Vendor contract provenance and operation inventories                    |
| `packages/`                                            | Workspace packages (the module adapters are still skeletons)            |
| `deploy/`                                              | Deployment examples: single-host Compose file, bootstrap file           |
| `scripts/`                                             | API contract tooling (fetch, reconcile, coverage report)                |
| `tests/`                                               | Contract, unit and security tests (later integration and compatibility) |

## Development

Requires Node.js 26.13.0+ (26.x LTS) and npm 11.

```sh
npm ci
npm run check              # format check, lint, typecheck, tests
npm run api:fetch-specs    # download and verify vendor API artefacts (internet needed)
npm run api:reconcile      # check the inventories against the vendor contracts
npm run unifi-mcp -- --help  # the host administration CLI from a source checkout
```

Never run `npx unifi-mcp`: that name on the public npm registry belongs to an unrelated
package, which `npx` would download and run.

## Licence

Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE). UniFi is a trademark of
Ubiquiti Inc.; this project is independent and not affiliated with Ubiquiti.