unifi-pro-mcp/docs/installation.md

MCP Server for UniFi Network and Protect systems with multi-device support

# Installation Guide

This guide provides comprehensive installation and configuration instructions for UniFi PRO MCP.

## 📋 Prerequisites

### System Requirements

- **Node.js**: Version 18.0.0 or higher
- **npm**: Version 8.0.0 or higher (comes with Node.js)
- **Operating System**: Windows 10+, macOS 10.15+, or Linux (Ubuntu 20.04+)
- **Memory**: Minimum 512MB RAM available
- **Network**: Direct network access to UniFi Controller

### UniFi Controller Requirements

- **UniFi Network Application**: Version 7.0.0 or higher
- **Network Access**: Controller must be accessible via HTTPS (default port 8443)
- **User Account**: Admin or Super Admin privileges required
- **API Access**: UniFi API must be enabled (enabled by default)

## 🚀 Installation Methods

### Method 1: Global Installation (Recommended)

Install globally for system-wide access:

```bash
npm install -g unifi-pro-mcp
```

Verify installation:
```bash
unifi-pro-mcp --version
```

### Method 2: Local Project Installation

For project-specific installations:

```bash
mkdir my-unifi-project
cd my-unifi-project
npm init -y
npm install unifi-pro-mcp
```

### Method 3: Development Installation

For contributors and developers:

```bash
git clone https://github.com/yourusername/unifi-pro-mcp.git
cd unifi-pro-mcp
npm install
npm run build
npm link
```

## 🔧 Configuration

### Environment Variables Setup

Create a `.env` file in your project directory or set system environment variables:

```bash
# Create .env file
touch .env

# Edit with your preferred editor
nano .env
```

Add the following configuration:

```env
# Required: UniFi Controller Connection
UNIFI_HOST=192.168.1.1
UNIFI_PORT=8443
UNIFI_USERNAME=admin
UNIFI_PASSWORD=your-secure-password
UNIFI_SITE=default

# Optional: SSL Configuration
UNIFI_SSL_VERIFY=true
UNIFI_TIMEOUT=30000

# Optional: Logging
MCP_LOG_LEVEL=info
MCP_LOG_FILE=/var/log/unifi-mcp.log

# Optional: Performance Tuning
MCP_CACHE_TTL=60
MCP_MAX_CONNECTIONS=10
```

### Configuration File Alternative

Create `unifi-mcp.config.json`:

```json
{
  "controller": {
    "host": "192.168.1.1",
    "port": 8443,
    "username": "admin",
    "password": "your-secure-password",
    "site": "default",
    "sslVerify": true,
    "timeout": 30000
  },
  "logging": {
    "level": "info",
    "file": "/var/log/unifi-mcp.log",
    "console": true
  },
  "cache": {
    "ttl": 60,
    "maxSize": 1000
  },
  "features": {
    "realTimeMonitoring": true,
    "guestNetworkManagement": true,
    "firewallManagement": true,
    "analytics": true,
    "backupManagement": true
  }
}
```

## 🤖 Claude Desktop Integration

### Configuration for Claude Desktop

1. Locate your Claude Desktop configuration file:

**macOS:**
```bash
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Windows:**
```bash
%APPDATA%\Claude\claude_desktop_config.json
```

**Linux:**
```bash
~/.config/Claude/claude_desktop_config.json
```

2. Add the UniFi PRO MCP server configuration:

```json
{
  "mcpServers": {
    "unifi-pro": {
      "command": "unifi-pro-mcp",
      "args": ["--config", "/path/to/unifi-mcp.config.json"],
      "env": {
        "UNIFI_HOST": "192.168.1.1",
        "UNIFI_USERNAME": "admin",
        "UNIFI_PASSWORD": "your-secure-password",
        "UNIFI_SITE": "default"
      }
    }
  }
}
```

3. Restart Claude Desktop

### Alternative: Environment File Method

```json
{
  "mcpServers": {
    "unifi-pro": {
      "command": "unifi-pro-mcp",
      "args": ["--env-file", "/path/to/.env"]
    }
  }
}
```

## 🔒 Security Configuration

### Secure Credential Management

**Option 1: Environment Variables (Recommended)**
```bash
export UNIFI_HOST="192.168.1.1"
export UNIFI_USERNAME="mcp-service-user"
export UNIFI_PASSWORD="$(cat /secure/path/unifi-password)"
```

**Option 2: Credential File**
```bash
# Create secure credential file
echo "your-password" > /secure/path/unifi-password
chmod 600 /secure/path/unifi-password
```

### SSL/TLS Configuration

**Production Environment (SSL Verification Enabled):**
```env
UNIFI_SSL_VERIFY=true
UNIFI_SSL_CERT_PATH=/path/to/controller-cert.pem
```

**Development Environment (Self-signed certificates):**
```env
UNIFI_SSL_VERIFY=false
```

### Firewall Configuration

Ensure the following ports are accessible:

- **Port 8443**: HTTPS API access to UniFi Controller
- **Port 8080**: HTTP access (if HTTP redirect is enabled)
- **Port 3478**: STUN port (for some features)

**Ubuntu/Debian:**
```bash
sudo ufw allow from YOUR_IP to any port 8443
```

**CentOS/RHEL:**
```bash
sudo firewall-cmd --permanent --add-port=8443/tcp
sudo firewall-cmd --reload
```

## ✅ Verification and Testing

### Connection Test

Test your configuration:

```bash
unifi-pro-mcp --test-connection
```

Expected output:
```
✅ UniFi Controller connection successful
✅ Authentication verified
✅ API access confirmed
✅ Site access verified
📊 Found 15 devices, 42 clients
```

### Debug Mode

Run in debug mode for troubleshooting:

```bash
unifi-pro-mcp --debug --test-connection
```

### Interactive Test

Test specific functionality:

```bash
# Test device discovery
unifi-pro-mcp --test devices

# Test client management
unifi-pro-mcp --test clients

# Test site statistics
unifi-pro-mcp --test stats
```

## 🔧 Advanced Configuration

### Multi-Site Setup

For managing multiple UniFi sites:

```json
{
  "sites": [
    {
      "name": "headquarters",
      "host": "192.168.1.1",
      "username": "admin",
      "password": "password1",
      "site": "default"
    },
    {
      "name": "branch-office",
      "host": "192.168.2.1", 
      "username": "admin",
      "password": "password2",
      "site": "branch"
    }
  ]
}
```

### Custom Logging Configuration

```json
{
  "logging": {
    "level": "debug",
    "transports": [
      {
        "type": "file",
        "filename": "/var/log/unifi-mcp.log",
        "maxsize": "10MB",
        "maxFiles": 5
      },
      {
        "type": "console",
        "colorize": true
      },
      {
        "type": "syslog",
        "host": "logs.example.com",
        "port": 514
      }
    ]
  }
}
```

### Performance Optimization

```json
{
  "performance": {
    "cacheEnabled": true,
    "cacheTTL": 300,
    "maxConcurrentRequests": 5,
    "requestTimeout": 30000,
    "retryAttempts": 3,
    "retryDelay": 1000
  }
}
```

## 🐛 Troubleshooting

### Common Installation Issues

**Issue: `npm install` fails with permission errors**
```bash
# Fix npm permissions (macOS/Linux)
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

# Alternative: Use npx
npx unifi-pro-mcp --version
```

**Issue: Node.js version too old**
```bash
# Install Node.js 18+ using nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18
```

**Issue: SSL certificate verification failures**
```bash
# Temporary solution (not recommended for production)
export NODE_TLS_REJECT_UNAUTHORIZED=0

# Better solution: Add certificate to trust store
export UNIFI_SSL_CERT_PATH=/path/to/controller-cert.pem
```

### Connection Issues

**Issue: Cannot connect to UniFi Controller**

1. **Verify controller is running:**
   ```bash
   curl -k https://YOUR_CONTROLLER_IP:8443/inform
   ```

2. **Check network connectivity:**
   ```bash
   ping YOUR_CONTROLLER_IP
   telnet YOUR_CONTROLLER_IP 8443
   ```

3. **Verify credentials:**
   ```bash
   unifi-pro-mcp --test-auth
   ```

**Issue: Authentication failures**

1. **Check user privileges:**
   - User must have Admin or Super Admin role
   - Enable "API Access" in user settings

2. **Verify credentials format:**
   ```env
   UNIFI_USERNAME=admin  # Not email address
   UNIFI_PASSWORD=actual-password  # Not encoded
   ```

**Issue: SSL/TLS errors**

1. **For self-signed certificates:**
   ```env
   UNIFI_SSL_VERIFY=false
   ```

2. **For production environments:**
   - Install proper SSL certificate on controller
   - Add certificate to system trust store

### Performance Issues

**Issue: Slow response times**

1. **Enable caching:**
   ```env
   MCP_CACHE_TTL=300
   ```

2. **Reduce request frequency:**
   ```json
   {
     "polling": {
       "interval": 60000,
       "enabled": false
     }
   }
   ```

3. **Optimize site selection:**
   ```env
   UNIFI_SITE=specific-site-id  # Instead of "default"
   ```

## 📞 Getting Help

If you encounter issues not covered in this guide:

1. **Check the logs:**
   ```bash
   tail -f /var/log/unifi-mcp.log
   ```

2. **Enable debug mode:**
   ```bash
   DEBUG=unifi-pro-mcp:* unifi-pro-mcp
   ```

3. **Create a GitHub issue** with:
   - Your configuration (remove sensitive data)
   - Log output
   - UniFi Controller version
   - Node.js version
   - Operating system

4. **Community Support:**
   - GitHub Discussions
   - UniFi Community Forums
   - MCP Community Discord

## 🔄 Updates and Maintenance

### Updating UniFi PRO MCP

```bash
# Check current version
unifi-pro-mcp --version

# Update to latest version
npm update -g unifi-pro-mcp

# Verify update
unifi-pro-mcp --version
```

### Configuration Migration

When updating, check for configuration changes:

```bash
# Backup current configuration
cp unifi-mcp.config.json unifi-mcp.config.json.backup

# Generate new configuration template
unifi-pro-mcp --generate-config > unifi-mcp.config.new.json
```

Compare and merge your settings with the new template.

---

**Next Steps:**
- [API Reference](api-reference.md) - Explore available tools and methods
- [Examples](examples.md) - See real-world usage scenarios
- [Security Guide](security.md) - Learn security best practices