unifi-network-mcp

ryanbehan/unifi-network-mcp

3.2

If you are the rightful owner of unifi-network-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The UniFi Network MCP is a read-only Model Context Protocol server that provides access to UniFi Network controller data for AI coding tools.

Tools
7
Resources
0
Prompts
0

UniFi Network MCP

Read-only data retriever for the UniFi Network application (UniFi OS and classic). Provides TypeScript library functions, a CLI, and an MCP server for LLM clients. This repo contains the TypeScript source, specs, and per-agent configuration snippets required to self-host the MCP.

Features

  • Multiple controller targets with independent auth, TLS, timeouts, and rate limits.

  • Auth flows: UniFi OS via POST /api/auth/login and classic via POST /api/login.

  • Routing: UniFi OS under /proxy/network/api/..., classic under /api/....

  • Network Integration API (API key) support:

    • GET /integration/v1/info → get_sysinfo
    • GET /integration/v1/sites → list_sites
    • GET /integration/v1/sites/{siteId}/devices → get_devices
    • GET /integration/v1/sites/{siteId}/clients → get_clients

  • Read-only only. No mutations.

Scope note: When connecting with an API key generated from the UniFi Network Integrations UI, only the Integration API endpoints listed above are guaranteed to work on UniFi Dream Machine / UniFi OS controllers. Endpoints such as stat/health, stat/event, and stat/report require username/password authentication and are not available to Integration API keys.

Prerequisites

  • Node.js 20+
  • npm 10+
  • A UniFi Network controller (UDM/UDR/UXG or UniFi OS gateway)
  • An Integration API key generated from UniFi Network → Settings → System → Integrations
  • git and a POSIX shell (macOS/Linux)

Configure & Build

  1. Clone and install:

    git clone https://github.com/ryanbehan/unifi-network-mcp.git
cd unifi-network-mcp/servers/unifi-network-mcp
npm install

  2. Export UNIFI_TARGETS (single or multiple controllers). Example:

    export UNIFI_TARGETS='[
  {
    "id": "home",
    "base_url": "https://<unifi_host>",
    "controller_type": "unifi_os",
    "default_site": "default",
    "auth": { "apiKey": "UNIFI_API_KEY", "headerName": "X-API-KEY" },
    "verify_ssl": false,
    "timeout_ms": 20000,
    "rate_limit_per_sec": 5
  }
]'

    Key fields:

    • id: Friendly name for this UniFi target (e.g. home, lab). Use this id as targetId in MCP tool calls when you have more than one controller.
    • base_url: The base URL of your UniFi controller (e.g. https://<unifi_host>). This is the same URL you use to access the UniFi Network UI.
    • auth.apiKey: UNIFI_API_KEY obtained from UniFi Network → Settings → System → Integrations for the Network Application.
    • default_site: Default site to use when a tool call does not specify site. Often Default; if your controller uses a different site name, check the Integration API Sites endpoint in the Network App.

    Multiple targets are supported:

    export UNIFI_TARGETS='[
  { "id": "home", "base_url": "https://<unifi_host_home>", "controller_type": "unifi_os", "default_site": "Default", "auth": { "apiKey": "UNIFI_API_KEY_HOME", "headerName": "X-API-KEY" }, "verify_ssl": false, "timeout_ms": 20000, "rate_limit_per_sec": 5 },
  { "id": "lab",  "base_url": "https://<unifi_host_lab>",  "controller_type": "unifi_os", "default_site": "Default", "auth": { "apiKey": "UNIFI_API_KEY_LAB",  "headerName": "X-API-KEY" }, "verify_ssl": false, "timeout_ms": 20000, "rate_limit_per_sec": 5 }
]'
    • When one target is configured, MCP tools can omit targetId and will automatically use that single target.
    • When multiple targets are configured, pass targetId (e.g. home or lab) in the MCP tool arguments so the server knows which controller to use.

    Example tool calls (multi-target):

    • List sites on home (default site):
      • Conceptual args: { "targetId": "home" }
    • Get devices from lab / Default site:
      • Conceptual args: { "targetId": "lab", "site": "Default" }
    • With Codex CLI, for example: 
      codex exec "call get_devices with targetId lab and site Default" --skip-git-repo-check

  3. Build once (emits dist/ artifacts shared by every tool below):

    npm run build

Quick Install from Release

curl -L https://github.com/ryanbehan/unifi-network-mcp/releases/download/v0.1.0/unifi-network-mcp-v0.1.0.tar.gz | tar -xz -C ~/.local/share/
cd ~/.local/share/unifi-network-mcp
cp .env.example .env
# Edit .env with your UNIFI_TARGETS

Common runtime command

All quickstarts use the same launch script, which validates UNIFI_TARGETS, builds on demand, and starts the MCP on STDIO:

cd /path/to/unifi-network-mcp
./run-mcp.sh

Leave this process running while your IDE/CLI talks to the MCP.

Tool-specific quickstarts

Windsurf / Cascade (npx)

  1. In Windsurf: Plugins → Model Context Protocol → Add MCP Server → Local Command.
  2. Command: npx
  3. Arguments: -y unifi-network-mcp
  4. Add env var UNIFI_TARGETS in the dialog (paste the JSON string) if not globally exported: 
    [{"id":"home","base_url":"https://<unifi_host>","controller_type":"unifi_os","default_site":"Default","auth":{"apiKey":"UNIFI_API_KEY","headerName":"X-API-KEY"},"verify_ssl":false,"timeout_ms":20000,"rate_limit_per_sec":5}]
  5. Save; Windsurf will fetch the MCP from npm automatically and expose the tools under My MCP Servers.

Cursor (npx)

  1. Create/update .cursor/mcp.config.json in your repo: 
    {
  "servers": [
    {
      "name": "unifi-network",
      "command": "npx",
      "args": ["-y", "unifi-network-mcp"],
      "env": {
        "UNIFI_TARGETS": "[{\"id\":\"home\",\"base_url\":\"https://<unifi_host>\",\"controller_type\":\"unifi_os\",\"default_site\":\"Default\",\"auth\":{\"apiKey\":\"UNIFI_API_KEY\",\"headerName\":\"X-API-KEY\"},\"verify_ssl\":false,\"timeout_ms\":20000,\"rate_limit_per_sec\":5}]"
      }
    }
  ]
}
  2. Reload Cursor (Cmd+Shift+P → "Reload Window"). Cursor will npx the MCP whenever needed.

Codex (npx-based install)

  1. Add this block to ~/.codex/config.toml: 
    [mcp_servers.unifi-network-mcp]
    command = "npx"
    args = ["-y", "unifi-network-mcp"]
    [mcp_servers.unifi-network-mcp.env]
        UNIFI_TARGETS = '[{"id":"home","base_url":"https://<unifi_host>","controller_type":"unifi_os","default_site":"Default","auth":{"apiKey":"UNIFI_API_KEY","headerName":"X-API-KEY"},"verify_ssl":false,"timeout_ms":20000,"rate_limit_per_sec":5}]'
    Tip: replace <API_KEY> and any controller metadata with your own values. Codex will download + cache the MCP automatically on first launch.
  2. From any repo, run codex exec list_sites --skip-git-repo-check to confirm connectivity.

Gemini CLI (npx)

  1. Install the Google gemini CLI (Early Access) and enable MCP support.
  2. Create ~/.gemini/mcp.yaml: 
    servers:
  - name: unifi-network
    command: npx
    args:
      - -y
      - unifi-network-mcp
    env:
      UNIFI_TARGETS: "[{\"id\":\"home\",\"base_url\":\"https://<unifi_host>\",\"controller_type\":\"unifi_os\",\"default_site\":\"Default\",\"auth\":{\"apiKey\":\"UNIFI_API_KEY\",\"headerName\":\"X-API-KEY\"},\"verify_ssl\":false,\"timeout_ms\":20000,\"rate_limit_per_sec\":5}]"
  3. Run gemini mcp servers list to confirm, then gemini chat --use-mcp unifi-network.

Amazon Q CLI (npx)

  1. Install the Amazon Q developer preview CLI.
  2. Edit ~/.aws/amazonq/mcp.json: 
    {
  "servers": [
    {
      "name": "unifi-network",
      "command": "npx",
      "args": ["-y", "unifi-network-mcp"],
      "env": {
        "UNIFI_TARGETS": "[{\"id\":\"home\",\"base_url\":\"https://<unifi_host>\",\"controller_type\":\"unifi_os\",\"default_site\":\"Default\",\"auth\":{\"apiKey\":\"UNIFI_API_KEY\",\"headerName\":\"X-API-KEY\"},\"verify_ssl\":false,\"timeout_ms\":20000,\"rate_limit_per_sec\":5}]"
      }
    }
  ]
}
  3. Launch Q CLI with amazon-q chat --mcp unifi-network.

Opencode

  1. Create or edit ~/.config/opencode/opencode.json: 
    {
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unifi-network-mcp": {
      "type": "local",
      "command": ["npx", "-y", "unifi-network-mcp"],
      "enabled": true,
      "environment": {
        "UNIFI_TARGETS": "[{\"id\":\"home\",\"base_url\":\"https://<unifi_host>\",\"controller_type\":\"unifi_os\",\"default_site\":\"Default\",\"auth\":{\"apiKey\":\"UNIFI_API_KEY\",\"headerName\":\"X-API-KEY\"},\"verify_ssl\":false,\"timeout_ms\":20000,\"rate_limit_per_sec\":5}]"
      }
    }
  }
}
  2. Restart Opencode or reload configuration; the unifi-network-mcp server will be available in chats.

Claude Code (Anthropic VS Code extension)

  1. Open VS Code Settings (JSON) (Command Palette → "Preferences: Open Settings (JSON)").
  2. Add or merge the following under the claude.mcpServers key: 
    "claude.mcpServers": {
  "unifi-network-mcp": {
    "command": "npx",
    "args": ["-y", "unifi-network-mcp"],
    "env": {
      "UNIFI_TARGETS": "[{\"id\":\"home\",\"base_url\":\"https://<unifi_host>\",\"controller_type\":\"unifi_os\",\"default_site\":\"Default\",\"auth\":{\"apiKey\":\"UNIFI_API_KEY\",\"headerName\":\"X-API-KEY\"},\"verify_ssl\":false,\"timeout_ms\":20000,\"rate_limit_per_sec\":5}]"
    }
  }
}
  3. Reload VS Code. Claude Code will launch the MCP via npm; verify with @mcp unifi-network-mcp list_sites in a Claude chat.

For Claude terminal / global config (outside VS Code), add the server to ~/.claude/settings.json:

{
  "mcpServers": {
    "unifi-network-mcp": {
      "command": "npx",
      "args": ["-y", "unifi-network-mcp"],
      "env": {
        "UNIFI_TARGETS": "[{\"id\":\"home\",\"base_url\":\"https://<unifi_host>\",\"controller_type\":\"unifi_os\",\"default_site\":\"Default\",\"auth\":{\"apiKey\":\"UNIFI_API_KEY\",\"headerName\":\"X-API-KEY\"},\"verify_ssl\":false,\"timeout_ms\":20000,\"rate_limit_per_sec\":5}]"
      }
    }
  }
}

After saving, restart Claude terminal or Desktop; the unifi-network-mcp server will be available there as well.

GitHub Copilot Chat (npx)

You can extend GitHub Copilot Chat with this MCP by adding a local server configuration in the same format documented by GitHub:

  • Per-repository (recommended): create a .vscode/mcp.json file in the root of your repo.
  • Global for VS Code: add the same JSON to your user settings.json under Copilot's MCP configuration (see GitHub docs for exact key names).

Example mcp.json contents for this server:

{
  "servers": {
    "unifi-network-mcp": {
      "command": "npx",
      "args": ["-y", "unifi-network-mcp"],
      "env": {
        "UNIFI_TARGETS": "[{\"id\":\"home\",\"base_url\":\"https://<unifi_host>\",\"controller_type\":\"unifi_os\",\"default_site\":\"Default\",\"auth\":{\"apiKey\":\"UNIFI_API_KEY\",\"headerName\":\"X-API-KEY\"},\"verify_ssl\":false,\"timeout_ms\":20000,\"rate_limit_per_sec\":5}]"
      }
    }
  }
}

Verifying

  • npm run test:env calls list_sites against every configured target and fails fast on TLS/auth errors.
  • Individual tool smoke tests: 
    codex exec get_sysinfo --skip-git-repo-check

Distribution options

To share a prebuilt MCP without requiring every consumer to run npm install:

  1. GitHub release artifacts
    • Run npm run build to populate dist/.
    • Package dist/, node_modules/, run-mcp.sh, and package.json into unifi-network-mcp-<version>.tar.gz.
    • Publish on GitHub Releases so others can download, set UNIFI_TARGETS, and run ./run-mcp.sh without compiling TypeScript.
  2. GitHub Pages / raw static hosting
    • Commit the tarball to a releases/ branch and serve via GitHub Pages for simple curl | tar installs.
  3. Homebrew-style tap (optional)
    • Create a formula that downloads the release tarball, verifies checksum, and places a wrapper script in /usr/local/bin.
  4. Container image (if runtime isolation is desired)
    • Build a minimal Node 20 image with dist/ copied in, expose STDIO via docker run --entrypoint ./run-mcp.sh ....

Each approach keeps the project free to distribute (only prebuilt JS + shell script) while letting downstream users skip the TypeScript toolchain.

Repository