Unimus MCP Server

A read-only Model Context Protocol server for Unimus network configuration management system. This server enables you to interact with your Unimus data directly via LLMs that support MCP.

Version

Current Version: 0.4.0 (Backup Content Search & Advanced Analysis)

🎉 FULLY TESTED & VALIDATED: All 13 MCP tools tested against live Unimus instance with real network data (17 devices, 960+ search matches, comprehensive Docker validation).

📦 Download v0.4.0 Release | See ROADMAP.md for future versions.

Features

Tools Available (v0.4.0)

Tool	Description
unimus_get_health	Get Unimus system health status
unimus_get_devices	Retrieve devices with filtering and automatic pagination
unimus_get_device_by_id	Get detailed device information by ID
unimus_get_device_by_address	Find device by IP address or hostname
unimus_get_device_backups	Get all configuration backups for a device
unimus_get_device_latest_backup	Get the most recent backup for a device
unimus_get_devices_by_description	Search devices by description (exact or partial match)
unimus_get_latest_backups	Get latest backups for multiple specific devices
unimus_get_backup_diff	NEW: Compare two backup configurations and show differences
unimus_get_devices_with_changed_backups	NEW: Find devices with backup changes in time range
unimus_get_schedules	NEW: Get all backup schedules
unimus_get_schedule_by_id	Get detailed schedule information
unimus_search_backup_content	NEW: Search through backup configurations with regex patterns

New in v0.4.0 🚀

• Backup Content Search: Search through backup configurations with regex patterns using unimus_search_backup_content
• Advanced Pattern Matching: Full regex support with case-insensitive, multiline search capabilities
• Context-Aware Results: Get configurable lines of context around matches for better understanding
• Smart Filtering: Combine device filters, time ranges, and search limits for optimal performance
• Detailed Match Information: Line numbers, regex capture groups, and context highlighting

Previous Updates

• v0.3.0: Backup Diff Analysis, Change Tracking, Schedule Management

• Backup Diff Analysis: Compare any two backup configurations with unimus_get_backup_diff

• Change Tracking: Find devices with backup changes in time ranges with unimus_get_devices_with_changed_backups

• Schedule Management: Access backup schedules with unimus_get_schedules and unimus_get_schedule_by_id

• Enhanced Analytics: Build powerful network change analysis workflows

Previous Updates

• v0.2.5: Automatic Base64 Decoding, Performance Optimization, Smart Content Handling
• v0.2.0: Enhanced Device Search and Bulk Backup Operations
• v0.1.0: Core device and backup functionality

Key Improvements over Basic API Access

• Transparent Pagination: Automatically handles paginated responses
• Enhanced Error Handling: Clear error messages with appropriate exception types
• Type Safety: Full type annotations for better development experience
• Connection Validation: Automatic validation of Unimus connectivity at startup
• Comprehensive Documentation: Detailed docstrings for all functions

Requirements

• Python 3.10+
• Unimus 1.7.x or newer (API v.2 support)
• Valid Unimus API token with read permissions

Installation

1. Clone or download this repository

2. Install the package and its dependencies:

   pip install .
   

   Or using uv (recommended for development):

   uv sync
   

   For development with optional dependencies:

   pip install .[dev]
   

Installation

Option 1: Docker (Recommended) 🐳

Quick Start:

docker run -d \
  --name unimus-mcp \
  -e UNIMUS_URL="https://your-unimus.example.com" \
  -e UNIMUS_TOKEN="your-api-token" \
  -p 8080:8080 \
  ghcr.io/deployment-team/unimus-mcp:latest

With Docker Compose:

git clone https://github.com/Deployment-Team/unimus-mcp.git
cd unimus-mcp
cp .env.example .env
# Edit .env with your Unimus details
docker-compose up -d

📖 Complete Docker guide: DOCKER.md

🩺 Health Monitoring:

• Liveness: http://localhost:8080/healthz - Container alive check
• Readiness: http://localhost:8080/readyz - Service ready check
• Legacy: http://localhost:8080/health - Backward compatibility

Option 2: Python Installation

Already covered above in the initial setup section.

Configuration

Environment Variables

Set the following environment variables:

• UNIMUS_URL: Full URL to your Unimus instance (e.g., https://unimus.example.com)
• UNIMUS_TOKEN: API token from Unimus (Bearer token)

Creating a Unimus API Token

1. Log into your Unimus web interface
2. Navigate to User Management > API Tokens
3. Create a new token with appropriate read permissions
4. Copy the token for use in the UNIMUS_TOKEN environment variable

Usage

Testing the Server

Verify the server can connect to your Unimus instance:

UNIMUS_URL=https://unimus.example.com UNIMUS_TOKEN=your-api-token python server.py

Configuring with LLM Clients

Claude Desktop (macOS)

Add to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "unimus": {
      "command": "python",
      "args": ["/path/to/unimus-mcp-server/server.py"],
      "env": {
        "UNIMUS_URL": "https://unimus.example.com",
        "UNIMUS_TOKEN": "your-api-token"
      }
    }
  }
}

Using uv (recommended)

{
  "mcpServers": {
    "unimus": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/unimus-mcp-server",
        "run",
        "server.py"
      ],
      "env": {
        "UNIMUS_URL": "https://unimus.example.com",
        "UNIMUS_TOKEN": "your-api-token"
      }
    }
  }
}

Windows

Use full, escaped paths:

{
  "mcpServers": {
    "unimus": {
      "command": "C:\\Users\\myuser\\AppData\\Local\\Programs\\Python\\Python311\\python.exe",
      "args": ["C:\\Users\\myuser\\unimus-mcp-server\\server.py"],
      "env": {
        "UNIMUS_URL": "https://unimus.example.com",
        "UNIMUS_TOKEN": "your-api-token"
      }
    }
  }
}

Example Queries

Once configured, you can use natural language queries with your LLM:

Device Management

> Show me all Cisco devices in my network
> Get details for device with ID 42
> Find the device at IP address 192.168.1.1
> List all unmanaged devices
> Search for devices with "router" in description
> Find devices with exact description "Main Core Switch"

Backup Operations

> Get the latest backup for device ID 15
> Show me all backups for the main router  
> How many backups do we have for our core switches?
> Get latest backups for devices 1, 5, and 10
> Retrieve recent backups for all core infrastructure devices

# No more waiting for base64 decoding - configs are instantly readable!

Backup Analysis & Diff (v0.3.0)

> Compare backup 100 with backup 105 and show me the differences
> What changed between these two router configurations?
> Find devices that had backup changes in the last 24 hours
> Show me all devices with configuration changes since yesterday
> Which devices had backup modifications between January 1st and today?

Schedule Management (v0.3.0)

> List all backup schedules in Unimus
> Show me the details of schedule ID 5
> What backup schedules are configured?
> Get information about the nightly backup schedule

Backup Content Search (v0.4.0)

> Search for "interface GigabitEthernet" in all Cisco device backups
> Find all VLAN configurations across RouterOS devices
> Search for "ip route" statements in the last 50 device backups
> Find access-list configurations with context lines
> Look for SNMP community strings in device configurations
> Search for "shutdown" commands in interface configurations
> Find devices with specific firmware versions in their configs

System Health

> Check Unimus system health
> Is the backup system running properly?

Advanced Filtering

> Show me all MikroTik RouterOS devices
> List devices that failed their last backup job
> Find all devices in zone 2

API Coverage

This implementation covers the core Unimus API endpoints for devices and backups based on the official Unimus API v.2 specification.

📚 IMPORTANT: All development must follow the official Unimus v2 API documentation
This document defines the complete API specification, request/response formats, and available endpoints.

Implemented Endpoints

• GET /api/v2/health - System health check
• GET /api/v2/devices - List devices (with filtering)
• GET /api/v2/devices/{id} - Get device by ID
• GET /api/v2/devices/findByAddress/{address} - Find device by address
• GET /api/v2/devices/findByDescription/{description} - Find devices by description
• GET /api/v2/devices/findByChangedBackup - NEW: Find devices with backup changes in time range
• GET /api/v2/devices/{id}/backups - Get device backups
• GET /api/v2/devices/{id}/backups/latest - Get latest device backup
• GET /api/v2/devices/backups/latest - Get latest backups for multiple devices
• GET /api/v2/backups/diff - NEW: Compare two backup configurations
• GET /api/v2/schedules - NEW: List all backup schedules
• GET /api/v2/schedules/{id} - NEW: Get individual schedule details

Note: Backup content search (unimus_search_backup_content) is implemented client-side since the Unimus API v.2 does not provide native content search endpoints.

Breaking Changes in v0.2.5

Important: This version contains breaking changes for better performance:

• Backup Content Format: The bytes field in backup responses has been replaced with:
  • content: Decoded content (readable text for TEXT backups, base64 for BINARY)
  • content_type: Format indicator ("text" or "base64")

Migration: If you have code that accesses backup["bytes"], change it to backup["content"]

Benefit: Massive performance improvement - no more artifact execution needed for reading configurations!

Performance Considerations

For large device inventories, consider using these optimization strategies:

• Use limit parameters: When searching by description or retrieving devices, use the limit parameter to control result size
• Bulk operations: Use unimus_get_latest_backups() instead of multiple individual calls
• Specific filtering: Apply vendor, type, or zone filters to reduce dataset size
• Targeted queries: Use exact matching when you know the precise description
• Optimized backups: v0.2.5+ automatically decodes TEXT backups for instant readability

⚠️ Important: Device Search Performance

Exact Match Warning: The unimus_get_devices_by_description() function with exact_match=True has specific performance characteristics:

• How it works: Retrieves ALL devices that partially match the description from the API, then filters them in Python
• Why necessary: The Unimus API only supports partial matching, so exact matching requires post-processing
• Performance impact: Can be slow with large device inventories

Best Practices:

# ✅ GOOD: Fast partial matching (default)
> Find devices with "router" in description

# ✅ GOOD: Exact match with limit (performance optimized)  
> Find devices with exact description "Main Core Router", limit to 10 results

# ⚠️ CAUTION: Exact match without limit (may be slow)
> Find devices with exact description "Core Switch" (no limit specified)

# 💡 TIP: Use additional filters to reduce dataset
> Show me Cisco devices with "router" in description, limit 20

Automatic Warnings: The system logs performance warnings when exact_match=True is used without a limit parameter.

Available Filters for Devices

• managed: Boolean (true/false) - Filter by management status
• vendor: String - Filter by vendor name (e.g., "Cisco", "MikroTik")
• type: String - Filter by device type (e.g., "IOS", "RouterOS")
• model: String - Filter by device model
• site_id: Number - Filter by site ID
• zone_id: String - Filter by zone ID
• address: String - Filter by device address
• description: String - Filter by description content

Error Handling

The server provides clear error messages for common issues:

• Authentication Errors: Invalid or expired API tokens
• Not Found Errors: Devices or resources that don't exist
• Validation Errors: Invalid parameters or malformed requests
• Connection Errors: Network connectivity issues

Security Considerations

• Use HTTPS for your Unimus URL in production
• Store API tokens securely (environment variables, not in code)
• Consider using read-only API tokens to limit access scope
• Regularly rotate API tokens according to your security policy

Troubleshooting

Common Issues

1. Connection Failed

   Failed to connect to Unimus at https://unimus.example.com
   

   • Verify UNIMUS_URL is correct and accessible
   • Check UNIMUS_TOKEN is valid and not expired
   • Ensure network connectivity to Unimus instance

2. Authentication Failed

   Authentication failed: Invalid token
   

   • Regenerate API token in Unimus
   • Verify token has appropriate read permissions

3. SSL Certificate Issues

   SSL verification failed
   

   • For development/testing with self-signed certificates, you may need to modify the client to skip SSL verification (not recommended for production)

4. Permission Denied

   API error (403): Insufficient permissions
   

   • Ensure API token has read access to devices and backups
   • Check user permissions in Unimus

Debug Mode

For debugging, you can increase log verbosity by modifying the logging level in server.py:

logging.basicConfig(level=logging.DEBUG)

Development

Project Structure

unimus-mcp-server/
├── server.py              # Main MCP server implementation
├── unimus_client.py       # Unimus REST API client library
├── requirements.txt       # Python dependencies
├── pyproject.toml        # Project configuration
├── README.md             # This documentation
├── ROADMAP.md           # Future development roadmap
└── .env.example         # Environment variables template

Code Quality

The project follows Python best practices:

• Type Hints: Full type annotations throughout
• Error Handling: Comprehensive exception handling with custom exception types
• Documentation: Detailed docstrings for all public methods
• Code Style: Black formatting and flake8 linting (see pyproject.toml)

Dependency Management

Dependencies are managed through pyproject.toml following modern Python packaging standards:

• Production dependencies: Defined in [project.dependencies]
• Development dependencies: Defined in [project.optional-dependencies.dev]
• Dependency pinning: uv.lock file ensures reproducible builds
• Installation: Use pip install . or uv sync for locked dependencies

Development Testing

✅ Comprehensive Validation Completed (v0.4.0)

ALL MCP functionality has been tested and validated against a live Unimus instance:

🎯 Test Instance: portal.sportfondsen.it:230
📊 Test Results Summary:
   • All 13 MCP tools: ✅ 100% functional
   • Total devices tested: 17 (all managed)
   • Backup operations: 5 backups per device tested
   • Schedule management: 3 schedules validated
   • Content search: 960 pattern matches found
   • Change tracking: 16 devices with recent changes
   • Docker containers: Build + health endpoints verified

Tested MCP Tools:

• ✅ unimus_get_health - System health status
• ✅ unimus_get_devices - Device listing and filtering
• ✅ unimus_get_device_by_id - Individual device details
• ✅ unimus_get_device_by_address - Device lookup by IP/hostname
• ✅ unimus_get_device_backups - Backup history retrieval
• ✅ unimus_get_device_latest_backup - Latest backup access
• ✅ unimus_get_devices_by_description - Search functionality
• ✅ unimus_get_latest_backups - Bulk backup operations
• ✅ unimus_get_backup_diff - Configuration comparison
• ✅ unimus_get_devices_with_changed_backups - Change tracking
• ✅ unimus_get_schedules - Schedule management
• ✅ unimus_get_schedule_by_id - Schedule details
• ✅ unimus_search_backup_content - v0.4.0 Regex content search

Development Testing Setup

For testing new features during development:

1. Test Environment Setup:

   # Create local test environment file (excluded from git)
   cp .env.test.example .env.test
   # Edit .env.test with your test Unimus credentials
   

2. Run Test Suite:

   # Load test environment and run comprehensive tests
   source .env.test
   python test_functionality.py
   

3. Manual Testing:

   # Test individual components
   source .env.test
   python -c "from unimus_client import UnimusRestClient; client = UnimusRestClient(...)"
   

Note: Test environment files are excluded from git commits for security. All functionality has been validated against real network infrastructure.

Contributing

Contributions are welcome! Please:

1. Follow the existing code style and patterns
2. Add appropriate type hints and documentation
3. Test changes against a real Unimus instance using the test framework
4. Update documentation as needed

Roadmap

This is version 0.1.0 focusing on core device and backup functionality. See ROADMAP.md for planned features:

• v0.2.0: Extended device operations and search capabilities
• v0.3.0: Backup analysis and diff operations
• v0.4.0: Schedule management and advanced queries
• v0.5.0: Performance optimizations and advanced features

License

This project is licensed under the MIT License. See the LICENSE file for details.

Compatibility

• Unimus API: Version 2 (Unimus 1.7.x and newer)
• Python: 3.10+
• MCP Protocol: Compatible with MCP 1.3.0+

⚠️ Development Note: This implementation strictly follows the official Unimus API v.2 specification. All features are based on documented endpoints and behaviors in the API documentation.

Support

For issues related to:

• This MCP Server: Open an issue in the project repository
• Unimus API: Consult the official Unimus API documentation
• MCP Protocol: See the Model Context Protocol documentation

---

Note: This implementation is based on Unimus API v.2 documentation. Always verify compatibility with your specific Unimus version and consult the official API documentation for the most current information.