nasuni-labs/local-nasuni-management-mcp-server

Nasuni Management MCP Server (Local)

A comprehensive Model Context Protocol (MCP) server that provides tools for interacting with your Nasuni environment (Nasuni Management Center (NMC) and Portal) through Claude AI integration. Using this MCP server, you can get granular details about your Nasuni environment, monitor the health of your appliances, summarize notifications, and generate custom reports.

Note: Nasuni Management MCP Server is Claude-specific using Anthropic's MCP framework.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Usage
• Available Tools
• Development
• Troubleshooting
• Contributing

Features

Infrastructure Management

• Filer(Edge) Management: List, monitor, and manage Edge Appliances
• Volume Operations: Comprehensive volume detail reporting
• Share Administration: SMB/CIFS Share management
• Health Monitoring: Real-time system health and performance monitoring

Analytics & Reporting

• Performance Metrics: Detailed system performance analytics
• Usage Statistics: Comprehensive usage reporting and analysis
• Notification Management: Centralized alert and notification handling

Support Statement

• Nasuni Support is limited to the underlying APIs used by the MCP Server.
• Nasuni API bugs or feature requests should be communicated to Nasuni Customer Success.
• GitHub project to-do's, bugs, and feature requests should be submitted as “Issues” in GitHub under its repositories.

Prerequisites

Python Requirements

• Python: Version 3.11+ or later is required
• Recommendation: Install the latest stable Python version for best performance and security

Checking Your Python Version

# Check version (should be 3.11+)
python --version
# or
python3 --version

Installing the Latest Python Version

Always install the latest stable Python version from the official Python website.

macOS (using Homebrew):

# If Python is installed but running a version older than 3.11
brew upgrade python

# Install latest Python (recommended)
brew install python

# Or install latest Python 3
brew install python@3

Windows:

1. Visit python.org/downloads
2. Download the latest Python version
3. Run the installer and make sure to check "Add Python to PATH"

Using pyenv (Cross-platform - Recommended for Developers):

# Install pyenv first, then:
pyenv install --list | grep "3\." | tail -5  # See latest versions
pyenv install 3.13.1  # Replace with latest version number
pyenv global 3.13.1   # Set as default
pyenv versions        # Verify installation

Linux (Ubuntu/Debian):

# Add deadsnakes PPA for latest Python versions
sudo apt update
sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update

# Install latest Python (check python.org for current version number)
sudo apt install python3.13 python3.13-pip python3.13-venv python3.13-dev

# Or use your distribution's latest available version
sudo apt install python3 python3-pip python3-venv

# For other Linux distributions:
# CentOS/RHEL/Fedora:
sudo dnf install python3 python3-pip python3-venv
# Arch Linux:
sudo pacman -S python python-pip

Claude AI Integration Requirements

• Claude AI Compatibility: This server is designed exclusively for Claude AI and uses Anthropic's Model Context Protocol (MCP) framework
• Claude Desktop Client: Required for local deployment - the MCP server integrates with Claude through the desktop application
  • Download: Get Claude Desktop Client
• Important: When running locally, MCP server tools are only accessible through the Claude Desktop Client, not through Claude's web interface

NMC API Requirements

-NMC Version: Recommended NMC Version 24.1.x or later

• NMC Credentials: Accessing the NMC API requires a user who is a member of an NMC group that has the "Enable NMC API Access" permission enabled
• API Permissions: Along with 'Enable NMC API Access', the API users must also have the corresponding NMC permission for each action they perform. For a granular permission set, refer to the Available Tools section.
• Account Types: Both native and domain accounts are supported for NMC API authentication (SSO accounts are not supported via the NMC API)

Installation

There are two options to install and configure the Nasuni Management MCP Server:

1. Automated Setup (Recommended)

2. Manual Setup

Option 1: Automated Setup (Recommended)

The automated installer handles all setup steps including downloading the code, creating virtual environment, installing dependencies, and configuring Claude Desktop.

1. Download the Installer Script

Download the installer.py from the repo.

2. Run the Installer

All Platforms:

python installer.py
# or
python3 installer.py

Step 3: Provide Required Information

During installation, you'll be prompted for:

1. Installation directory

   • Default: ~/nasuni-management-mcp-server (Mac/Linux) or %USERPROFILE%\nasuni-management-mcp-server (Windows)
   • Press Enter to accept default or specify a custom path

2. NMC Server URL

   • Example: https://nmc.company.com or https://192.168.1.100
   • The installer will add https:// if not provided

3. NMC Username

   • Your NMC login username
   • For domain accounts: DOMAIN\username or just username

4. NMC Password

   • Your NMC login password
   • Input is hidden for security

5. SSL Certificate Verification

   • Default: No (recommended for internal servers)
   • Choose 'y' only if your NMC has valid SSL certificates

Step 4: Restart Claude Desktop and Test

1. Close Claude Desktop completely (not just minimize)
2. Start Claude Desktop again
3. Test the integration by asking Claude:
   • "List all my filers"
   • "Show unhealthy volumes"
   • "Get share statistics"

If Claude Desktop was not installed when you ran the installer:

1. Install Claude Desktop from claude.ai/download
2. Run the configuration script that was created:

   python ~/nasuni-management-mcp-server/configure_claude.py
   

Manual Setup

1. Clone or Download the Repository

Clone

git clone https://github.com/nasuni-labs/local-nasuni-management-mcp-server.git nasuni-management-mcp-server
cd nasuni-management-mcp-server

Or Download Download the zip file and unzip in a new folder 'nasuni-management-mcp-server'

https://github.com/nasuni-labs/local-nasuni-management-mcp-server/archive/refs/heads/main.zip

2. Create Virtual Environment (Recommended)

# Create virtual environment
python3 -m venv nasuni-management-mcp-server-env

# Activate virtual environment
# On macOS/Linux:
source nasuni-management-mcp-desktop-server-env/bin/activate
# On Windows:
nasuni-management-mcp-env\Scripts\activate

3. Install Dependencies

# Use pip3 to ensure you're using Python 3.x package manager
pip3 install -r requirements.txt

# Alternative: if pip3 is not available, use pip
pip install -r requirements.txt

Note about pip vs pip3:

• Use pip3 if you have both Python 2 and Python 3 installed
• Use pip if you only have Python 3 installed or if pip3 is not available
• When in a virtual environment, both commands typically point to the same Python 3 version

4. Verify Installation

# Check that Python 3.13+ is being used
python --version

# Verify dependencies are installed
pip3 list | grep -E "(mcp-server|httpx|python-dotenv)"

5. Set Up Environment

Create a .env file in the project root:

cp .env.example .env

Configuration

Environment Variables

Configure the following environment variables in your .env file:

Required Configuration

# NMC API Base URL (replace with your actual NMC server)
API_BASE_URL="https://your-nmc-server.com"

# NMC Login Credentials (Ensure the user has adequate permissions)
NMC_USERNAME="username"
NMC_PASSWORD="password"

# SSL Verification (set to true for production)
VERIFY_SSL=false

Optional Configuration

# API Request Timeout (seconds)
API_TIMEOUT=30.0

Development/Debugging Configuration

# Uncomment for development
# DEBUG=true
# LOG_LEVEL=DEBUG

Authentication Setup

The Nasuni Management MCP Server uses username and password authentication to connect to your NMC instance:

1. Username: Your NMC login username
2. Password: Your NMC login password
3. Permissions: Ensure the user account has:
   • 'Enable NMC API Access' permission
   • Filer Access ('Manage All Filers (super user)' or intended subset of Filers)
   • Appropriate permissions for the operations you want to perform

Security Note: The credentials are stored in your local .env file and are only used to authenticate with your NMC server.

Verification (Optional)

Test your configuration:

python -c "
import asyncio
from main import diagnose_system
asyncio.run(diagnose_system())
"

Usage

Starting the Server

For Claude Integration

python main.py

Diagnostic Mode (Optional)

python -c "
import asyncio
from main import diagnose_system
asyncio.run(diagnose_system())
"

Tool Testing (Optional)

python -c "
import asyncio
from main import test_all_tools
asyncio.run(test_all_tools())
"

Claude Desktop Integration

Configure your .env file as described above, then add the JSON config to your Claude configuration file (usually claude_desktop_config.json):

Step 1: Find Your Python Executable Path

First, determine the correct Python executable path:

# Find your Python executable path
which python3
# or
which python

# If using a virtual environment (recommended), activate it first:
source nasuni-management-mcp-server/bin/activate  # macOS/Linux
# nmc-mcp-env\Scripts\activate   # Windows
which python

Common Python paths:

• macOS (Homebrew): /opt/homebrew/bin/python3 or /usr/local/bin/python3
• macOS (pyenv): /Users/yourusername/.pyenv/shims/python
• Linux: /usr/bin/python3 or /usr/local/bin/python3
• Windows: C:\Python313\python.exe or C:\Users\yourusername\AppData\Local\Programs\Python\Python313\python.exe
• Virtual Environment: /path/to/nmc-mcp-env/bin/python (macOS/Linux) or C:\path\to\nmc-mcp-env\Scripts\python.exe (Windows)

Step 2: Update Claude Desktop Configuration

Add this configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "nasuni-management": {
      "command": "/path/to/your/python/executable",
      "args": ["/full/path/to/nasuni-management-mcp-server/main.py"]
    }
  }
}

Example configurations:

Using virtual environment (recommended):

{
  "mcpServers": {
    "nasuni-management": {
      "command": "/Users/john/Projects/nasuni-management-mcp-server/nasuni-management-mcp-server-env/bin/python",
      "args": ["/Users/john/Projects/nasuni-management-mcp-server/main.py"]
    }
  }
}

Using system Python:

{
  "mcpServers": {
    "nasuni-management-mcp-server": {
      "command": "/opt/homebrew/bin/python3",
      "args": ["/Users/john/Projects/nasuni-management-mcp-server/main.py"]
    }
  }
}

Step 3: Locate Claude Desktop Config File

On your Claude Desktop Client -> Settings -> Developer -> Edit Config -> claude_desktop_config.json

Step 4: Restart Claude Desktop

After updating the configuration file, restart the Claude Desktop application to load the new MCP server.

Setup Complete

Test your Nasuni Management MCP Server, ask Claude "List all my filers with details"

Available Tools

Note: All tools require 'Enable NMC API Access' permissions.

Filer Management

• list_filers - List all filer with hardware details
• get_filer_stats - Get aggregate statistics about all filers
• get_filer - Get detailed information about a specific filer
• get_volumes_by_filer - Get all volumes connected to a filer

Required Permissions:

• Manage All Filers or a set of Filers
• Filer Access (Manage All Filers (super user) or intended subset of Filers)
• Manage Volume Settings (Can't add/delete).

Volume Operations

• list_volumes - List all storage volumes with comprehensive details
• get_volume_access_summary - Get volume ownership and access summary
• find_unprotected_volumes - Identify volumes with unprotected data
• analyze_volume_operations - Comprehensive volume operations analysis

Required Permissions:

• Manage All Filers or a set of Filers
• Filer Access (Manage All Filers (super user) or intended subset of Filers)
• Manage Volume Settings (Can't add/delete).

Share Management

• list_shares - List all SMB/CIFS Shares
• get_share_stats - Get comprehensive Share statistics
• get_shares_by_filer - Get Shares on a specific filer
• get_browser_accessible_shares - Get shares with web browser access

Required Permissions:

• Manage All Filers or a set of Filers
• Filer Access (Manage All Filers (super user) or intended subset of Filers)
• Manage Shares, Exports, FTP and ISCSI

Health Monitoring

• list_filer_health - Get health status for all filers
• get_filer_health_stats - Get health statistics across infrastructure
• get_unhealthy_filers - Identify filers requiring attention
• get_critical_health_issues - Get prioritized critical health issues

Required Permissions:

• Manage All Filers or a set of Filers
• Filer Access (Manage All Filers (super user) or intended subset of Filers)

Authentication & Security

• refresh_auth_token - Refresh authentication token
• check_auth_token_status - Check token validity and expiration
• ensure_valid_auth_token - Auto-refresh token if needed

Cloud Credentials

• list_cloud_credentials - List configured cloud credentials
• get_credential_stats - Get cloud credential statistics
• analyze_credential_usage - Analyze credential usage patterns

Required Permissions:

• Manage all aspects of the Filer (super user)

📊 Notifications & Monitoring

• list_notifications - List system notifications with filtering
• get_notification_summary - Get notification statistics and summaries
• analyze_notification_patterns - Identify recurring issues and trends

Required Permissions:

• Manage Notifications (Both NMC and Filer Permissions)

Development

To foster further colloboartion, here is project structure and details on how to add support for new APIs and tools:

Project Structure

nasuni-management-mcp-server/
├── main.py                 # Main entry point and diagnostics
├── requirements.txt        # Python dependencies
├── .env.example           # Environment configuration template
├── server/
│   └── mcp_server.py      # Main MCP server implementation
├── api/                   # API client implementations
│   ├── base_client.py     # Base API client class
│   ├── filers_api.py      # Filer management API
│   ├── volumes_api.py     # Volume management API
│   ├── shares_api.py      # Share management API
│   └── ...
├── tools/                 # MCP tool implementations
│   ├── base_tool.py       # Base tool class
│   ├── filer_tools.py     # Filer-related tools
│   ├── volume_tools.py    # Volume-related tools
│   └── registry.py        # Tool registration system
├── models/                # Data model classes
│   ├── base.py           # Base model classes
│   ├── filer.py          # Filer data models
│   └── volume.py         # Volume data models
├── config/                # Configuration management
│   └── settings.py       # Configuration loader
└── utils/                 # Utility functions
    └── formatting.py     # Output formatting utilities

Adding New Tools

1. Create a new tool class inheriting from BaseTool:

from tools.base_tool import BaseTool

class MyCustomTool(BaseTool):
    def __init__(self, api_client):
        super().__init__(
            name="my_custom_tool",
            description="Description of what this tool does"
        )
        self.api_client = api_client
    
    def get_schema(self):
        return {
            "type": "object",
            "properties": {
                "parameter": {
                    "type": "string",
                    "description": "Parameter description"
                }
            }
        }
    
    async def execute(self, arguments):
        # Tool implementation
        pass

2. Register the tool in tools/registry.py:

def register_custom_tools(self, api_client):
    self.register_tool(MyCustomTool(api_client))

Adding New API Clients

1. Create an API client inheriting from BaseAPIClient:

from api.base_client import BaseAPIClient

class MyAPIClient(BaseAPIClient):
    async def get_data(self):
        return await self.get("/api/v1.2/my-endpoint/")

2. Register in server/mcp_server.py:

def _setup_tools(self):
    # ... existing setup ...
    my_client = MyAPIClient(config.api_config)
    self.tool_registry.register_custom_tools(my_client)

Troubleshooting

Common Issues

Connection Errors

# Test API connectivity
python -c "
import asyncio
from api.filers_api import FilersAPIClient
from config.settings import config

async def test():
    client = FilersAPIClient(config.filers_config)
    result = await client.test_connection()
    print('Connection:', 'Success' if result else 'Failed')

asyncio.run(test())
"

Authentication Issues

# Check token status
python -c "
import asyncio
from main import diagnose_system
asyncio.run(diagnose_system())
"

Tool Registration Problems

# List available tools
python -c "
from server.mcp_server import MCPServer
server = MCPServer()
print('Available tools:', server.tool_registry.get_tool_names())
"

Debugging

Enable detailed logging by setting:

DEBUG=true
LOG_LEVEL=DEBUG

Performance Optimization

• Connection Pooling: The server uses HTTP connection pooling for optimal performance
• Token Caching: Authentication tokens are cached and auto-refreshed
• Concurrent Requests: NMC API calls are throlled at 5 requests per second. Learn More

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Testing

Run the comprehensive test suite:

python -c "
import asyncio
from main import test_all_tools, diagnose_system

async def full_test():
    await diagnose_system()
    await test_all_tools()

asyncio.run(full_test())
"

Note: This server is designed for Nasuni environments and requires proper network access and authentication to your NMC infrastructure.