UISP API MCP Server

A Model Context Protocol (MCP) server for interacting with UISP (Ubiquiti Internet Service Provider) API. This server dynamically loads all available endpoints from the UISP swagger specification and provides configurable access control through blacklisting.

Features

• Dynamic Tool Generation: Automatically creates MCP tools from swagger.json

• Comprehensive Coverage: Exposes all UISP API endpoints (GET, POST, PUT, DELETE, PATCH)

• Configurable Blacklist: Control which endpoints are exposed via blacklist.yaml

• Method-Based Filtering: Block entire HTTP methods (e.g., all POST/PUT/DELETE operations)

• Type Safety: Preserves parameter types and enum values from API spec

• Smart Parameter Handling: Correctly handles both path and query parameters

• Automatic Retries: Built-in retry logic with exponential backoff

• Detailed Error Messages: Rich error information from API responses

Installation

Using UV (recommended)

cd uisp_api_mcp
uv sync

Using pip

cd uisp_api_mcp
pip install -e .

Configuration

Environment Variables

Create a .env file in the project root:

# Required
UISP_BASE_URL=https://your-uisp-instance.com
UISP_API_TOKEN=your-api-token

# Optional (with defaults)
UISP_API_TIMEOUT=30.0
UISP_API_RETRY_ATTEMPTS=3
UISP_API_RETRY_DELAY=1.0
UISP_DEFAULT_PAGE_SIZE=25
UISP_LOG_LEVEL=INFO

Blacklist Configuration

The server uses etc/blacklist.yaml to control which endpoints are exposed. By default, all modifying operations (POST, PUT, DELETE, PATCH) and sensitive endpoints are blacklisted.

# Methods to exclude (blocks all endpoints using these HTTP methods)
methods:
  - POST      # Create operations
  - PUT       # Update operations
  - DELETE    # Delete operations
  - PATCH     # Partial update operations

# Tags to exclude (blocks all endpoints with these tags)
tags:
  - Authorization
  - Users
  - Server
  # ... etc

# Path patterns to exclude (regex patterns)
paths:
  - .*login.*
  - .*password.*
  - .*auth.*
  # ... etc

With the default configuration, only GET (read-only) operations are exposed.

Getting UISP API Token

1. Log in to your UISP instance

2. Navigate to Settings → Users

3. Select your user account

4. Generate an API token

Usage

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "uisp": {
      "command": "uv",
      "args": ["--directory", "/path/to/uisp_api_mcp", "run", "uisp-api-mcp"],
      "env": {
        "UISP_BASE_URL": "https://your-uisp-instance.com",
        "UISP_API_TOKEN": "your-api-token"
      }
    }
  }
}

Command Line

# With UV
uv run uisp-api-mcp

# With Python
python -m uisp_api_mcp

Available Tools

The server dynamically generates tools from the UISP swagger specification. With the default blacklist (blocking all POST, PUT, DELETE, PATCH methods), approximately 120+ read-only tools are available, including:

Common Tools

• Sites: sites, sites_id, sites_search, sites_traffic

• Devices: devices, devices_id, devices_id_detail, devices_id_statistics

• Monitoring: logs, outages, nms_statistics, nms_summary

• Network: datalinks, datalinks_id, devices_id_interfaces

• System Info: nms_info, nms_version, nms_enums

Tool Naming Convention

Tools are named based on the API endpoint path and HTTP method:

• GET /sites → sites

• GET /sites/{id} → sites_id

• GET /devices/{id}/detail → devices_id_detail

• POST /sites → sites_post (if not blacklisted)

• PUT /sites/{id} → sites_id_put (if not blacklisted)

• DELETE /sites/{id} → sites_id_delete (if not blacklisted)

Parameter Types

All tools preserve the original API parameter types:

• String enums show available values (e.g., "Available values: site, endpoint, client")

• Required vs optional parameters are properly marked

• Path parameters (like {id}) are automatically handled

Examples

List all sites

Tool: sites
Parameters:
  - type_: "site"  # Available values: site, endpoint, client, subscriber
  - ucrm: true     # Only sites bound with CRM

Get specific site details

Tool: sites_id
Parameters:
  - id_: "9ef86767-fd8d-487c-8c97-77f763c5a99a"
  - ucrmDetails: true

List devices

Tool: devices
Parameters:
  - siteId: "site-uuid"
  - type_: ["erouter", "eswitch"]  # Device types
  - role: ["router", "switch"]      # Device roles

Get device statistics

Tool: devices_id_statistics
Parameters:
  - id_: "device-uuid"
  - interval: "hour"
  - start: "2024-01-01T00:00:00Z"
  - period: "86400000"  # 24 hours in milliseconds

Error Handling

The server includes comprehensive error handling:

• Authentication errors (401)

• Not found errors (404)

• Validation errors (400)

• Rate limiting (429)

• Connection timeouts

• Automatic retry with exponential backoff

Development

Project Structure

uisp_api_mcp/
├── pyproject.toml
├── README.md
├── .env
├── etc/
│   ├── swagger.json      # UISP API specification
│   └── blacklist.yaml    # Endpoint blacklist configuration
└── src/
    └── uisp_api_mcp/
        ├── __init__.py
        ├── __main__.py
        ├── client.py       # HTTP client with retry logic
        ├── exceptions.py   # Custom exception types
        ├── server.py       # Dynamic MCP server
        ├── settings.py     # Configuration management
        └── swagger_tools.py # Swagger parsing and tool generation

How It Works

1. Swagger Loading: The server reads etc/swagger.json at startup

2. Blacklist Filtering: Endpoints are filtered based on etc/blacklist.yaml (methods, tags, paths)

3. Tool Generation: Each allowed endpoint becomes an MCP tool with proper types

4. Parameter Handling: Path parameters are substituted, query parameters are passed

5. Error Handling: API errors are caught and enriched with details

Adding/Removing Endpoints

To modify which endpoints are exposed:

1. Edit etc/blacklist.yaml

2. Add or remove:

   • HTTP methods (e.g., remove POST from methods list to allow POST operations)

   • Tags (to block/allow all endpoints with specific tags)

   • Path patterns (regex patterns to match specific endpoints)

3. Restart the server

Updating the API Spec

To update with a newer UISP API version:

1. Replace etc/swagger.json with the latest version

2. The server will automatically pick up new endpoints

License

MIT License - see LICENSE file for details.

Support

For UISP API documentation, visit: https://help.ui.com/hc/en-us/articles/115002943188-UISP-API

For issues with this MCP server, please open an issue on GitHub.