unifi-mcp-server
Advanced tools
UniFi MCP Server
A Model Context Protocol (MCP) server that exposes the UniFi Network Controller API, enabling AI agents and applications to interact with UniFi network infrastructure in a standardized way.
Current Stable Release: v0.2.0 (2026-01-25) 🎉
What's New in v0.2.0:
See CHANGELOG.md for complete release notes and VERIFICATION_REPORT.md for detailed verification.
The UniFi MCP Server supports three distinct API modes with different capabilities:
Full feature support - Direct access to your UniFi gateway.
UNIFI_API_TYPE=local + UNIFI_LOCAL_HOST=<gateway-ip>Limited to aggregate statistics - UniFi cloud API in testing phase.
UNIFI_API_TYPE=cloud-eaLimited to aggregate statistics - UniFi stable v1 cloud API.
UNIFI_API_TYPE=cloud-v1💡 Recommendation: Use Local Gateway API (UNIFI_API_TYPE=local) for full functionality. Cloud APIs are suitable only for high-level monitoring dashboards.
confirm=True flagdry_run=Trueaudit.log for compliance# Install from PyPI (when published)
pip install unifi-mcp-server==0.2.0
# Or using uv (faster)
uv pip install unifi-mcp-server==0.2.0
# Install metadata package from npm
npm install unifi-mcp-server
# Note: This is a metadata wrapper. The actual server is Python-based.
# Install the Python server using pip as shown above.
# Pull the latest release
docker pull ghcr.io/enuno/unifi-mcp-server:0.2.0
# Multi-architecture support: amd64, arm64, arm/v7
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone the repository
git clone https://github.com/enuno/unifi-mcp-server.git
cd unifi-mcp-server
# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"
# Clone the repository
git clone https://github.com/enuno/unifi-mcp-server.git
cd unifi-mcp-server
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install -e ".[dev]"
The recommended way to run the UniFi MCP Server with full monitoring capabilities:
# 1. Copy and configure environment variables
cp .env.docker.example .env
# Edit .env with your UNIFI_API_KEY and AGNOST_ORG_ID
# 2. Start all services (MCP Server + Redis + MCP Toolbox)
docker-compose up -d
# 3. Check service status
docker-compose ps
# 4. View logs
docker-compose logs -f unifi-mcp
# 5. Access MCP Toolbox dashboard
open http://localhost:8080
# 6. Stop all services
docker-compose down
Included Services:
See MCP_TOOLBOX.md for detailed Toolbox documentation.
For standalone Docker usage (not with MCP clients):
# Pull the image
docker pull ghcr.io/enuno/unifi-mcp-server:latest
# Run the container in background (Cloud API)
# Note: -i flag keeps stdin open for STDIO transport
docker run -i -d \
--name unifi-mcp \
-e UNIFI_API_KEY=your-api-key \
-e UNIFI_API_TYPE=cloud \
ghcr.io/enuno/unifi-mcp-server:latest
# OR run with local gateway proxy
docker run -i -d \
--name unifi-mcp \
-e UNIFI_API_KEY=your-api-key \
-e UNIFI_API_TYPE=local \
-e UNIFI_HOST=192.168.1.1 \
ghcr.io/enuno/unifi-mcp-server:latest
# Check container status
docker ps --filter name=unifi-mcp
# View logs
docker logs unifi-mcp
# Stop and remove
docker rm -f unifi-mcp
Note: For MCP client integration (Claude Desktop, etc.), see the Usage section below for the correct configuration without -d flag.
git clone https://github.com/enuno/unifi-mcp-server.git
cd unifi-mcp-server
Using uv (Recommended):
# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh
# Create virtual environment
uv venv
# Activate virtual environment
source .venv/bin/activate # Linux/macOS
# Or on Windows: .venv\Scripts\activate
# Install development dependencies
uv pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
pre-commit install --hook-type commit-msg
Using pip:
# Create virtual environment
python -m venv .venv
# Activate virtual environment
source .venv/bin/activate # Linux/macOS
# Or on Windows: .venv\Scripts\activate
# Upgrade pip
pip install --upgrade pip
# Install development dependencies
pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
pre-commit install --hook-type commit-msg
# Copy example configuration
cp .env.example .env
# Edit .env with your UniFi credentials
# Required: UNIFI_API_KEY
# Recommended: UNIFI_API_TYPE=local, UNIFI_LOCAL_HOST=<gateway-ip>
# Run all unit tests
pytest tests/unit/ -v
# Run with coverage report
pytest tests/unit/ --cov=src --cov-report=html --cov-report=term-missing
# View coverage report
open htmlcov/index.html # macOS
# Or: xdg-open htmlcov/index.html # Linux
# Development mode with MCP Inspector
uv run mcp dev src/main.py
# Production mode
uv run python -m src.main
# The MCP Inspector will be available at http://localhost:5173
# Install build tools
uv pip install build
# Build wheel and source distribution
python -m build
# Output: dist/unifi_mcp_server-0.2.0-py3-none-any.whl
# dist/unifi_mcp_server-0.2.0.tar.gz
# Build for current architecture
docker build -t unifi-mcp-server:0.2.0 .
# Build multi-architecture (requires buildx)
docker buildx create --use
docker buildx build \
--platform linux/amd64,linux/arm64,linux/arm/v7 \
-t ghcr.io/enuno/unifi-mcp-server:0.2.0 \
--push .
# Test the image
docker run -i --rm \
-e UNIFI_API_KEY=your-key \
-e UNIFI_API_TYPE=cloud \
unifi-mcp-server:0.2.0
# Install twine
uv pip install twine
# Check distribution
twine check dist/*
# Upload to PyPI (requires PyPI account and token)
twine upload dist/*
# Or upload to Test PyPI first
twine upload --repository testpypi dist/*
# Ensure package.json is up to date
cat package.json
# Login to npm (if not already)
npm login
# Publish package
npm publish --access public
# Verify publication
npm view unifi-mcp-server
# Install mcp-publisher
brew install mcp-publisher
# Or: curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/
# Authenticate with GitHub (for io.github.enuno namespace)
mcp-publisher login github
# Publish to registry (requires npm package published first)
mcp-publisher publish
# Verify
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.enuno/unifi-mcp-server"
The project uses automated releases via GitHub Actions:
Tag the Release:
git tag -a v0.2.0 -m "Release v0.2.0"
git push origin v0.2.0
GitHub Actions Automatically:
Manual Steps:
See RELEASE_COMPLETION_GUIDE.md for detailed release procedures.
.env fileCreate a .env file in the project root:
# Required: Your UniFi API Key
UNIFI_API_KEY=your-api-key-here
# API Mode Selection (choose one):
# - 'local': Full access via local gateway (RECOMMENDED)
# - 'cloud-ea': Early Access cloud API (limited to statistics)
# - 'cloud-v1': Stable v1 cloud API (limited to statistics)
UNIFI_API_TYPE=local
# Local Gateway Configuration (for UNIFI_API_TYPE=local)
UNIFI_LOCAL_HOST=192.168.1.1
UNIFI_LOCAL_PORT=443
UNIFI_LOCAL_VERIFY_SSL=false
# Cloud API Configuration (for cloud-ea or cloud-v1)
# UNIFI_CLOUD_API_URL=https://api.ui.com
# Optional settings
UNIFI_DEFAULT_SITE=default
# Redis caching (optional - improves performance)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
# REDIS_PASSWORD=your-password # If Redis requires authentication
# Webhook support (optional - for real-time events)
WEBHOOK_SECRET=your-webhook-secret-here
# Performance tracking with agnost.ai (optional - for analytics)
# Get your Organization ID from https://app.agnost.ai
# AGNOST_ENABLED=true
# AGNOST_ORG_ID=your-organization-id-here
# AGNOST_ENDPOINT=https://api.agnost.ai
# AGNOST_DISABLE_INPUT=false # Set to true to disable input tracking
# AGNOST_DISABLE_OUTPUT=false # Set to true to disable output tracking
See .env.example for all available options.
# Development mode with MCP Inspector
uv run mcp dev src/main.py
# Production mode
uv run python src/main.py
The MCP Inspector will be available at http://localhost:5173 for interactive testing.
Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"unifi": {
"command": "uv",
"args": [
"--directory",
"/path/to/unifi-mcp-server",
"run",
"mcp",
"run",
"src/main.py"
],
"env": {
"UNIFI_API_KEY": "your-api-key-here",
"UNIFI_API_TYPE": "cloud"
}
}
}
}
{
"mcpServers": {
"unifi": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"UNIFI_API_KEY=your-api-key-here",
"-e",
"UNIFI_API_TYPE=cloud",
"ghcr.io/enuno/unifi-mcp-server:latest"
]
}
}
}
Important: Do NOT use -d (detached mode) in MCP client configurations. The MCP client needs to maintain a persistent stdin/stdout connection to the container.
from mcp import MCP
import asyncio
async def main():
mcp = MCP("unifi-mcp-server")
# List all devices
devices = await mcp.call_tool("list_devices", {
"site_id": "default"
})
for device in devices:
print(f"{device['name']}: {device['status']}")
# Get network information via resource
networks = await mcp.read_resource("sites://default/networks")
print(f"Networks: {len(networks)}")
# Create a guest WiFi network with VLAN isolation
wifi = await mcp.call_tool("create_wlan", {
"site_id": "default",
"name": "Guest WiFi",
"security": "wpapsk",
"password": "GuestPass123!",
"is_guest": True,
"vlan_id": 100,
"confirm": True # Required for safety
})
print(f"Created WiFi: {wifi['name']}")
# Get DPI statistics for top bandwidth users
top_apps = await mcp.call_tool("list_top_applications", {
"site_id": "default",
"limit": 5,
"time_range": "24h"
})
for app in top_apps:
gb = app['total_bytes'] / 1024**3
print(f"{app['application']}: {gb:.2f} GB")
# Create Zone-Based Firewall zones (UniFi Network 9.0+)
lan_zone = await mcp.call_tool("create_firewall_zone", {
"site_id": "default",
"name": "LAN",
"description": "Trusted local network",
"confirm": True
})
iot_zone = await mcp.call_tool("create_firewall_zone", {
"site_id": "default",
"name": "IoT",
"description": "Internet of Things devices",
"confirm": True
})
# Set zone-to-zone policy (LAN can access IoT, but IoT cannot access LAN)
await mcp.call_tool("update_zbf_policy", {
"site_id": "default",
"source_zone_id": lan_zone["_id"],
"destination_zone_id": iot_zone["_id"],
"action": "accept",
"confirm": True
})
asyncio.run(main())
See API.md for complete API documentation, including:
# Install development dependencies
uv pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
pre-commit install --hook-type commit-msg
# Run all tests
pytest tests/unit/
# Run with coverage report
pytest tests/unit/ --cov=src --cov-report=html --cov-report=term-missing
# Run specific test file
pytest tests/unit/test_zbf_tools.py -v
# Run tests for new v0.2.0 features
pytest tests/unit/test_new_models.py tests/unit/test_zbf_tools.py tests/unit/test_traffic_flow_tools.py
# Run only unit tests (fast)
pytest -m unit
# Run only integration tests (requires UniFi controller)
pytest -m integration
Current Test Coverage (v0.2.0):
By Module Category:
Top Coverage Performers (>95%):
See VERIFICATION_REPORT.md for complete coverage details and TESTING_PLAN.md for testing strategy.
# Format code
black src/ tests/
isort src/ tests/
# Lint code
ruff check src/ tests/ --fix
# Type check
mypy src/
# Run all pre-commit checks
pre-commit run --all-files
# Start development server with inspector
uv run mcp dev src/main.py
# Open http://localhost:5173 in your browser
unifi-mcp-server/
├── .github/
│ └── workflows/ # CI/CD pipelines (CI, security, release)
├── .claude/
│ └── commands/ # Custom slash commands for development
├── src/
│ ├── main.py # MCP server entry point (77 tools registered)
│ ├── cache.py # Redis caching implementation
│ ├── config/ # Configuration management
│ ├── api/ # UniFi API client with rate limiting
│ ├── models/ # Pydantic data models
│ │ └── zbf.py # Zone-Based Firewall models
│ ├── tools/ # MCP tool definitions
│ │ ├── clients.py # Client query tools
│ │ ├── devices.py # Device query tools
│ │ ├── networks.py # Network query tools
│ │ ├── sites.py # Site query tools
│ │ ├── firewall.py # Firewall management (Phase 4)
│ │ ├── firewall_zones.py # Zone-Based Firewall zone management (v0.1.4)
│ │ ├── zbf_matrix.py # Zone-Based Firewall policy matrix (v0.1.4)
│ │ ├── network_config.py # Network configuration (Phase 4)
│ │ ├── device_control.py # Device control (Phase 4)
│ │ ├── client_management.py # Client management (Phase 4)
│ │ ├── wifi.py # WiFi/SSID management (Phase 5)
│ │ ├── port_forwarding.py # Port forwarding (Phase 5)
│ │ └── dpi.py # DPI statistics (Phase 5)
│ ├── resources/ # MCP resource definitions
│ ├── webhooks/ # Webhook receiver and handlers (Phase 5)
│ └── utils/ # Utility functions and validators
├── tests/
│ ├── unit/ # Unit tests (213 tests, 37% coverage)
│ ├── integration/ # Integration tests (planned)
│ └── performance/ # Performance benchmarks (planned)
├── docs/ # Additional documentation
│ └── AI-Coding/ # AI coding guidelines
├── .env.example # Environment variable template
├── pyproject.toml # Project configuration
├── README.md # This file
├── API.md # Complete API documentation
├── ZBF_STATUS.md # Zone-Based Firewall implementation status
├── TESTING_PLAN.md # Testing strategy and roadmap
├── DEVELOPMENT_PLAN.md # Development roadmap
├── CONTRIBUTING.md # Contribution guidelines
├── SECURITY.md # Security policy and best practices
├── AGENTS.md # AI agent guidelines
└── LICENSE # Apache 2.0 License
We welcome contributions from both human developers and AI coding assistants! Please see:
git checkout -b feature/your-feature-namepytest && pre-commit run --all-filesfeat: add new featureSecurity is a top priority. Please see SECURITY.md for:
Never commit credentials or sensitive data!
All 7 Feature Phases Complete - 74 MCP Tools
Phase 3: Read-Only Operations (16 tools)
Phase 4: Mutating Operations with Safety (13 tools)
Phase 5: Advanced Features (11 tools)
Phase 6: Zone-Based Firewall (12 working tools)
Phase 7: Traffic Flow Monitoring (15 tools) ✅ COMPLETE
ZBF Implementation Notes (Verified 2025-11-18):
Phase 1: QoS Enhancements (11 tools) ✅
Phase 2: Backup & Restore (8 tools) ✅
Phase 3: Multi-Site Aggregation (4 tools) ✅
Phase 4: ACL & Traffic Filtering (7 tools) ✅
Phase 5: Site Management Enhancements (9 tools) ✅
Phase 6: RADIUS & Guest Portal (6 tools) ✅
Phase 7: Network Topology (5 tools) ✅
Quality Achievements:
Total: 74 MCP tools + Comprehensive documentation and verification
This project is inspired by and builds upon:
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
io.github.enuno/unifi-mcp-server at https://registry.modelcontextprotocol.ioIf you find this project useful, please consider starring it on GitHub to help others discover it!
Made with ❤️ for the UniFi and AI communities
FAQs
An MCP server that leverages official UniFi API
The npm package unifi-mcp-server receives a total of 29 weekly downloads. As such, unifi-mcp-server popularity was classified as not popular.
We found that unifi-mcp-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A misconfiguration gave three Anthropic models internet access, and one, believing it was in a simulation, shipped a credential-stealing package to PyPI.
Security News
/Company News
Socket has joined the new Composer and Packagist sponsorship program as a launch sponsor, supporting the team that keeps PHP's package ecosystem secure.
Research
/Security News
Benign-looking npm packages split malicious functionality across a dependency chain that deploys a cross-platform RAT targeting Alibaba developers.