MCP 服务器

UISP API MCP Server

Enables interaction with Ubiquiti UISP API for managing network devices, sites, and monitoring through dynamically generated read-only tools.

README

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

Log in to your UISP instance
Navigate to Settings → Users
Select your user account
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

Swagger Loading: The server reads etc/swagger.json at startup
Blacklist Filtering: Endpoints are filtered based on etc/blacklist.yaml (methods, tags, paths)
Tool Generation: Each allowed endpoint becomes an MCP tool with proper types
Parameter Handling: Path parameters are substituted, query parameters are passed
Error Handling: API errors are caught and enriched with details

Adding/Removing Endpoints

To modify which endpoints are exposed:

Edit etc/blacklist.yaml
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)
Restart the server