UniFi Network MCP Server

Model Context Protocol server for the UniFi Network Integration API.

It turns curated UniFi Network endpoints into MCP-callable skills, loaded from JSON manifests at runtime. The server is read-only by default: READ_ONLY=true exposes only GET skills and the executor blocks writes as a second guard.

Highlights

• Manifest-driven endpoint catalog in skills/network

• Read-only default with runtime write protection

• Compact dispatcher tool surface to keep MCP context small

• Docker Compose and stdio support

• Self-signed UniFi certificate support

• Connector wildcard proxy endpoints hidden and blocked

Related MCP server: MCP from API

Quick Start

Docker Compose

Edit docker-compose.yml with your UniFi console URL and API key, then run:

./build.sh

The MCP endpoint is:

http://127.0.0.1:8000/mcp

The Compose file publishes only to host loopback:

ports:
  - "127.0.0.1:8000:8000"

Do not change this to 8000:8000 unless you intend to expose the server on all host interfaces and have added real authentication. The Docker image binds to 0.0.0.0 inside the container so Docker can forward the published port to the Python process.

Local Python

Requires Python 3.12 or newer.

python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'

UNIFI_BASE_URL='https://172.16.1.1/proxy/network/integration' \
UNIFI_API_KEY='<api-key>' \
python -m unifi_mcp

For stdio clients:

MCP_TRANSPORT=stdio \
UNIFI_BASE_URL='https://172.16.1.1/proxy/network/integration' \
UNIFI_API_KEY='<api-key>' \
python -m unifi_mcp

MCP Tools

The server intentionally exposes three MCP tools instead of one tool per UniFi endpoint:

This keeps the MCP tool list small while still giving the model exact schemas before it calls an endpoint.

Skill calls use this shape:

{
  "pathParams": { "siteId": "..." },
  "queryParams": { "limit": 25, "offset": 0 },
  "body": {}
}

body is accepted only when the selected skill schema includes a request body. With the default READ_ONLY=true, exposed skills are GET-only and do not need a body.

Configuration

Only UNIFI_BASE_URL and UNIFI_API_KEY are required. READ_ONLY=true is the secure default and is shown in Compose as an explicit safety setting.

Do not set both a direct secret env var and its _FILE variant. Startup fails on ambiguous secret configuration.

Skills

Runtime manifests live in skills/network and are generated from docs/network:

python3 scripts/import_unifi_docs.py --source docs/network --output skills/network

The importer writes endpoint manifests only. Guide documents such as _index.json, gettingstarted.json, filtering.json, error-handling.json, and quick_start.ansible.json are ignored.

Generated manifests preserve endpoint paths, parameters, request bodies, responses, descriptions, required flags, types, and discriminators.

Connector wildcard proxy endpoints are generated from upstream docs but are not exposed at runtime. Add curated endpoint manifests instead of enabling broad proxy access.

Development

python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
pytest
ruff check .