# sirkirby/unifi-mcp architecture

> Architecture diagram of the GitHub repository sirkirby/unifi-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sirkirby/unifi-mcp
- Repository: https://github.com/sirkirby/unifi-mcp

## Overview

UniFi MCP is a suite for AI assistants and applications to operate UniFi Network, Protect, and Access, alongside an independent REST/GraphQL API and optional Cloud Relay. The primary workflow is client discovery and invocation of a domain server’s tools, which interact with UniFi controllers; the API offers an alternative HTTP path for custom applications. Cloud Relay routes remote MCP requests through a Worker to a LAN sidecar and then to local MCP servers. The README documents product-level links; unsampled implementation details are kept broad rather than inferred.

Main entry points: [`apps/api/src/unifi_api`](https://github.com/sirkirby/unifi-mcp/tree/main/apps/api/src/unifi_api) (API Server), [`packages/unifi-core/src/unifi_core`](https://github.com/sirkirby/unifi-mcp/tree/main/packages/unifi-core/src/unifi_core) (UniFi Core Managers), [`apps/network/src/unifi_network_mcp`](https://github.com/sirkirby/unifi-mcp/tree/main/apps/network/src/unifi_network_mcp) (Network Tools), [`apps/protect/src/unifi_protect_mcp`](https://github.com/sirkirby/unifi-mcp/tree/main/apps/protect/src/unifi_protect_mcp) (Protect Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP Servers"]
  node_network["Network Tools"]
  node_protect["Protect Tools"]
  node_access["Access Tools"]
end

subgraph group_api["HTTP API"]
  node_api_server["API Server"]
  node_rest["REST Resources"]
  node_graphql["GraphQL Queries"]
  node_streams["SSE Streams"]
  node_actions["Controller Actions<br/>[actions.py]"]
  node_auth["Scoped API Keys"]
  node_admin["Administration"]
end

subgraph group_relay["Cloud Relay"]
  node_worker["Worker Gateway"]
  node_broker["Durable Object Broker<br/>[relay-object.ts]"]
  node_sidecar["Relay Sidecar"]
end

subgraph group_core["Shared Runtime"]
  node_core["UniFi Core Managers"]
  node_shared["MCP Shared Runtime"]
end

node_assistant(("MCP Client"))
node_controller{{"UniFi Controllers"}}
node_customapp(("Custom Application"))
node_relay_client(("Remote MCP Client"))

node_assistant -->|"discovers and invokes"| node_network
node_assistant -->|"discovers and invokes"| node_protect
node_assistant -->|"discovers and invokes"| node_access
node_network -->|"manages"| node_controller
node_protect -->|"manages"| node_controller
node_access -->|"manages"| node_controller
node_customapp -->|"calls"| node_api_server
node_api_server -->|"serves"| node_rest
node_api_server -->|"serves"| node_graphql
node_api_server -->|"serves"| node_streams
node_api_server -->|"routes"| node_actions
node_api_server -->|"enforces scopes"| node_auth
node_api_server -->|"provides"| node_admin
node_rest -->|"uses managers"| node_core
node_graphql -->|"uses managers"| node_core
node_actions -->|"uses managers"| node_core
node_core -->|"operates"| node_controller
node_relay_client -->|"sends MCP requests"| node_worker
node_worker -->|"routes requests"| node_broker
node_worker -->|"forwards by WebSocket"| node_sidecar
node_sidecar -->|"forwards over HTTP"| node_network
node_sidecar -->|"forwards over HTTP"| node_protect
node_sidecar -->|"forwards over HTTP"| node_access
node_network -->|"uses runtime"| node_shared
node_protect -->|"uses runtime"| node_shared
node_access -->|"uses runtime"| node_shared
node_network -.->|"uses managers"| node_core
node_protect -.->|"uses managers"| node_core
node_access -.->|"uses managers"| node_core

click node_network "https://github.com/sirkirby/unifi-mcp/tree/main/apps/network/src/unifi_network_mcp"
click node_protect "https://github.com/sirkirby/unifi-mcp/tree/main/apps/protect/src/unifi_protect_mcp"
click node_access "https://github.com/sirkirby/unifi-mcp/tree/main/apps/access/src/unifi_access_mcp"
click node_api_server "https://github.com/sirkirby/unifi-mcp/tree/main/apps/api/src/unifi_api"
click node_rest "https://github.com/sirkirby/unifi-mcp/tree/main/apps/api/src/unifi_api/routes/resources"
click node_graphql "https://github.com/sirkirby/unifi-mcp/tree/main/apps/api/src/unifi_api/graphql"
click node_streams "https://github.com/sirkirby/unifi-mcp/tree/main/apps/api/src/unifi_api/routes/streams"
click node_actions "https://github.com/sirkirby/unifi-mcp/blob/main/apps/api/src/unifi_api/routes/actions.py"
click node_auth "https://github.com/sirkirby/unifi-mcp/tree/main/apps/api/src/unifi_api/auth"
click node_admin "https://github.com/sirkirby/unifi-mcp/tree/main/apps/api/src/unifi_api/routes/admin"
click node_worker "https://github.com/sirkirby/unifi-mcp/tree/main/apps/worker/worker/src"
click node_broker "https://github.com/sirkirby/unifi-mcp/blob/main/apps/worker/worker/src/relay-object.ts"
click node_sidecar "https://github.com/sirkirby/unifi-mcp/tree/main/packages/unifi-mcp-relay/src/unifi_mcp_relay"
click node_core "https://github.com/sirkirby/unifi-mcp/tree/main/packages/unifi-core/src/unifi_core"
click node_shared "https://github.com/sirkirby/unifi-mcp/tree/main/packages/unifi-mcp-shared/src/unifi_mcp_shared"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_network,node_protect,node_access,node_assistant,node_relay_client toneBlue
class node_api_server,node_rest,node_graphql,node_streams,node_actions,node_auth,node_admin toneAmber
class node_worker,node_broker,node_sidecar toneMint
class node_core,node_shared toneRose
class node_controller,node_customapp toneIndigo
```

## Components

### MCP Servers

- [Network Tools](https://github.com/sirkirby/unifi-mcp/tree/main/apps/network/src/unifi_network_mcp): `apps/network/src/unifi_network_mcp`
- [Protect Tools](https://github.com/sirkirby/unifi-mcp/tree/main/apps/protect/src/unifi_protect_mcp): `apps/protect/src/unifi_protect_mcp`
- [Access Tools](https://github.com/sirkirby/unifi-mcp/tree/main/apps/access/src/unifi_access_mcp): `apps/access/src/unifi_access_mcp`

### HTTP API

- [API Server](https://github.com/sirkirby/unifi-mcp/tree/main/apps/api/src/unifi_api): `apps/api/src/unifi_api`
- [REST Resources](https://github.com/sirkirby/unifi-mcp/tree/main/apps/api/src/unifi_api/routes/resources): `apps/api/src/unifi_api/routes/resources`
- [GraphQL Queries](https://github.com/sirkirby/unifi-mcp/tree/main/apps/api/src/unifi_api/graphql): `apps/api/src/unifi_api/graphql`
- [SSE Streams](https://github.com/sirkirby/unifi-mcp/tree/main/apps/api/src/unifi_api/routes/streams): `apps/api/src/unifi_api/routes/streams`
- [Controller Actions](https://github.com/sirkirby/unifi-mcp/blob/main/apps/api/src/unifi_api/routes/actions.py): `apps/api/src/unifi_api/routes/actions.py`
- [Scoped API Keys](https://github.com/sirkirby/unifi-mcp/tree/main/apps/api/src/unifi_api/auth): `apps/api/src/unifi_api/auth`
- [Administration](https://github.com/sirkirby/unifi-mcp/tree/main/apps/api/src/unifi_api/routes/admin): `apps/api/src/unifi_api/routes/admin`

### Cloud Relay

- [Worker Gateway](https://github.com/sirkirby/unifi-mcp/tree/main/apps/worker/worker/src): `apps/worker/worker/src`
- [Durable Object Broker](https://github.com/sirkirby/unifi-mcp/blob/main/apps/worker/worker/src/relay-object.ts): `apps/worker/worker/src/relay-object.ts`
- [Relay Sidecar](https://github.com/sirkirby/unifi-mcp/tree/main/packages/unifi-mcp-relay/src/unifi_mcp_relay): `packages/unifi-mcp-relay/src/unifi_mcp_relay`

### Shared Runtime

- [UniFi Core Managers](https://github.com/sirkirby/unifi-mcp/tree/main/packages/unifi-core/src/unifi_core): `packages/unifi-core/src/unifi_core`
- [MCP Shared Runtime](https://github.com/sirkirby/unifi-mcp/tree/main/packages/unifi-mcp-shared/src/unifi_mcp_shared): `packages/unifi-mcp-shared/src/unifi_mcp_shared`

### Other components

- **MCP Client**
- **UniFi Controllers**
- **Custom Application**
- **Remote MCP Client**

## Connections

- MCP Client → Network Tools: discovers and invokes (evidence: `README.md`)
- MCP Client → Protect Tools: discovers and invokes (evidence: `README.md`)
- MCP Client → Access Tools: discovers and invokes (evidence: `README.md`)
- Network Tools → UniFi Controllers: manages (evidence: `README.md`)
- Protect Tools → UniFi Controllers: manages (evidence: `README.md`)
- Access Tools → UniFi Controllers: manages (evidence: `README.md`)
- Custom Application → API Server: calls (evidence: `README.md`)
- API Server → REST Resources: serves (evidence: `README.md`)
- API Server → GraphQL Queries: serves (evidence: `README.md`)
- API Server → SSE Streams: serves (evidence: `README.md`)
- API Server → Controller Actions: routes (evidence: `README.md`)
- API Server → Scoped API Keys: enforces scopes (evidence: `README.md`)
- API Server → Administration: provides (evidence: `README.md`)
- REST Resources → UniFi Core Managers: uses managers (evidence: `README.md`)
- GraphQL Queries → UniFi Core Managers: uses managers (evidence: `README.md`)
- Controller Actions → UniFi Core Managers: uses managers (evidence: `README.md`)
- UniFi Core Managers → UniFi Controllers: operates (evidence: `README.md`)
- Remote MCP Client → Worker Gateway: sends MCP requests (evidence: `README.md`)
- Worker Gateway → Durable Object Broker: routes requests (evidence: `README.md`)
- Worker Gateway → Relay Sidecar: forwards by WebSocket (evidence: `README.md`)
- Relay Sidecar → Network Tools: forwards over HTTP (evidence: `README.md`)
- Relay Sidecar → Protect Tools: forwards over HTTP (evidence: `README.md`)
- Relay Sidecar → Access Tools: forwards over HTTP (evidence: `README.md`)
- Network Tools → MCP Shared Runtime: uses runtime (evidence: `apps/network/src/unifi_network_mcp/main.py`)
- Protect Tools → MCP Shared Runtime: uses runtime (evidence: `apps/protect/src/unifi_protect_mcp/main.py`)
- Access Tools → MCP Shared Runtime: uses runtime (evidence: `apps/access/src/unifi_access_mcp/main.py`)
- Network Tools → UniFi Core Managers: uses managers (evidence: `apps/network/src/unifi_network_mcp/tools/traffic_routes.py`)
- Protect Tools → UniFi Core Managers: uses managers (evidence: `apps/protect/src/unifi_protect_mcp/main.py`)
- Access Tools → UniFi Core Managers: uses managers (evidence: `apps/access/src/unifi_access_mcp/main.py`)
