andreransom58-coder/qnap-mcp-server

QNAP MCP Server

A Model Context Protocol (MCP) server for managing your QNAP NAS (192.168.1.130) from Claude Desktop.

Features

• Volume Management: List volumes, check storage usage, RAID status
• Share Management: List and create shared folders
• System Monitoring: CPU, memory, disk health, network stats
• Disk Information: SMART data, temperature, health status
• Snapshot Management: List and create volume snapshots
• User Management: List system users
• Docker Integration: List and manage containers
• Service Monitoring: Check running services and system status
• Custom Commands: Execute any SSH command on your NAS

Installation

1. Install Dependencies

cd qnap-mcp-server
npm install

2. Set Up SSH Access

Option A: SSH Key (Recommended for Security)

Generate an SSH key pair if you don't have one:

ssh-keygen -t rsa -b 4096 -f ~/.ssh/qnap_nas_key -N ""

Copy the public key to your QNAP NAS:

ssh-copy-id -i ~/.ssh/qnap_nas_key.pub admin@192.168.1.130

Or manually on QNAP:

1. SSH into your QNAP: ssh admin@192.168.1.130
2. Create SSH directory: mkdir -p ~/.ssh && chmod 700 ~/.ssh
3. Add your public key: cat >> ~/.ssh/authorized_keys (paste key, then Ctrl+D)
4. Set permissions: chmod 600 ~/.ssh/authorized_keys

Option B: Password Authentication

You can use password authentication (less secure) by setting the password in environment variables.

3. Configure Claude Desktop

Edit your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Add the QNAP MCP server configuration:

{
  "mcpServers": {
    "qnap": {
      "command": "node",
      "args": ["/absolute/path/to/qnap-mcp-server/index.js"],
      "env": {
        "QNAP_HOST": "192.168.1.130",
        "QNAP_SSH_PORT": "22",
        "QNAP_USERNAME": "admin",
        "QNAP_SSH_KEY_PATH": "/home/your-username/.ssh/qnap_nas_key",
        "QNAP_USE_SSL": "true",
        "QNAP_HTTPS_PORT": "443"
      }
    }
  }
}

Using Password Instead of SSH Key (not recommended):

{
  "mcpServers": {
    "qnap": {
      "command": "node",
      "args": ["/absolute/path/to/qnap-mcp-server/index.js"],
      "env": {
        "QNAP_HOST": "192.168.1.130",
        "QNAP_SSH_PORT": "22",
        "QNAP_USERNAME": "admin",
        "QNAP_PASSWORD": "your-password-here",
        "QNAP_USE_SSL": "true",
        "QNAP_HTTPS_PORT": "443"
      }
    }
  }
}

4. Enable SSH on QNAP

If SSH is not already enabled:

1. Log into QNAP web interface (https://192.168.1.130)
2. Go to Control Panel → Network & File Services → Telnet / SSH
3. Check Allow SSH connection
4. Set SSH port (default: 22)
5. Click Apply

5. Restart Claude Desktop

After saving the configuration, completely quit and restart Claude Desktop for the changes to take effect.

Available Tools

Volume & Storage

• qnap_list_volumes - List all storage volumes with size, usage, and RAID status
• qnap_disk_info - Get physical disk information and SMART health data
• qnap_list_snapshots - List volume snapshots
• qnap_create_snapshot - Create a new volume snapshot

Shares & Files

• qnap_list_shares - List all shared folders
• qnap_create_share - Create a new shared folder
• qnap_backup_status - Check backup job status

System Monitoring

• qnap_system_info - Get model, firmware, uptime, and system details
• qnap_cpu_usage - Real-time CPU usage and processes
• qnap_memory_usage - Memory usage and statistics
• qnap_network_info - Network interfaces and statistics
• qnap_running_services - List all running services

Docker & Containers

• qnap_docker_containers - List Docker containers (if Container Station is installed)

User Management

• qnap_list_users - List system user accounts

Advanced

• qnap_execute_command - Execute any custom SSH command

Usage Examples

Once configured, you can interact with your QNAP NAS through Claude Desktop:

"Show me all volumes on my QNAP"
"What's the disk health status?"
"Create a new share called 'Projects' on DataVol1"
"What's the CPU and memory usage?"
"List all running Docker containers"
"Create a snapshot of DataVol1 called 'backup-2024-12-09'"
"Show me network statistics"

Security Considerations

1. Use SSH Keys: Always prefer SSH key authentication over passwords
2. Restrict SSH Access: Consider limiting SSH access to specific IP addresses in QNAP firewall
3. Regular Updates: Keep your QNAP firmware updated
4. Monitor Access: Regularly check SSH logs on your QNAP
5. Backup Keys: Keep a secure backup of your SSH private key
6. File Permissions: Ensure SSH key has correct permissions (chmod 600)

Troubleshooting

"Connection refused" error

• Check if SSH is enabled on QNAP
• Verify the SSH port (default: 22)
• Check firewall settings on QNAP

"Permission denied" error

• Verify SSH key permissions: chmod 600 ~/.ssh/qnap_nas_key
• Ensure public key is in QNAP's ~/.ssh/authorized_keys
• Check QNAP SSH settings allow key authentication

"Module not found" error

• Run npm install in the qnap-mcp-server directory
• Verify Node.js version (requires Node.js 18+)

Tools not appearing in Claude

• Restart Claude Desktop completely
• Check the configuration file path is correct
• Verify JSON syntax in config file
• Check MCP server logs in Claude Desktop developer tools

Testing SSH Connection

Test your SSH connection manually:

# With SSH key
ssh -i ~/.ssh/qnap_nas_key admin@192.168.1.130

# With password
ssh admin@192.168.1.130

Environment Variables

Advanced Configuration

Custom SSH Port

If using a non-standard SSH port:

"env": {
  "QNAP_SSH_PORT": "2222"
}

Multiple QNAP Servers

You can configure multiple QNAP servers:

{
  "mcpServers": {
    "qnap-main": {
      "command": "node",
      "args": ["/path/to/qnap-mcp-server/index.js"],
      "env": {
        "QNAP_HOST": "192.168.1.130"
      }
    },
    "qnap-backup": {
      "command": "node",
      "args": ["/path/to/qnap-mcp-server/index.js"],
      "env": {
        "QNAP_HOST": "192.168.1.131"
      }
    }
  }
}

Logs and Debugging

Check Claude Desktop logs:

• macOS: ~/Library/Logs/Claude/
• Windows: %APPDATA%\Claude\logs\
• Linux: ~/.config/Claude/logs/

Enable debug mode by adding to environment:

"NODE_ENV": "development"

License

MIT

Support

For issues or questions about this MCP server, check the logs or verify your QNAP SSH connectivity manually.