MCP Server Disk Usage

🚀 Disk Usage Tool

This project is a user - friendly tool designed to retrieve and display disk usage information on macOS systems. It operates via the MCP protocol and has been integrated into Claude Desktop.

🚀 Quick Start

Prerequisites

• Operating System: macOS (This tool is specifically designed for Mac)
• Python Version: 3.11+
• Dependency Management Tool: pip

Installation Steps

1. Clone this repository to your local machine.
2. Install the required Python packages by running the following command in the terminal:

pip install -r requirements.txt

3. Start the server:

python disk_usage_server.py

⚠️ Important Note

This server is specifically designed for Mac's /System/Volumes/Data partition (i.e., disk3s5) and cannot run on other operating systems.

Integration with Claude Desktop

1. Create a file named claude - config.txt in the configuration directory of Claude Desktop.
2. Paste the following content into the file:

{
    "mcpServers": {
        "disk - usage": {
            "command": "python3",
            "args": [
                "<Your actual path>/disk_usage_server.py"
            ]
        }
    }
}

3. Replace <Your actual path> with the actual location where the server file is saved.
4. Restart Claude Desktop to apply the configuration.

✨ Features

• Real - time Data: Monitor the real - time usage of specific partitions.
• Detailed Information: Provide detailed disk usage information, including used space, available space, reserved space, and usage percentage.
• macOS - Specific: Specifically designed for the /System/Volumes/Data partition on Mac systems.

📦 Installation

Environment Requirements

• Operating System: macOS
• Python Version: 3.11+
• Dependency Management Tool: pip

Installation Steps

1. Clone the repository locally.
2. Install Python packages:

pip install -r requirements.txt

3. Start the server:

python disk_usage_server.py

💻 Usage Examples

Basic Usage

import subprocess
import json
from datetime import datetime, timezone
from http.server import BaseHTTPRequestHandler, HTTPServer

class DiskUsageRequestHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        # Determine the partition to query (here, it is Mac's /System/Volumes/Data)
        target_partition = '/System/Volumes/Data'
        
        try:
            # Use the df command to get disk usage
            result = subprocess.run(['df', '-h'], capture_output=True, text=True, check=True)
            
            # Parse the output of the df command
            output_lines = result.stdout.split('\n')
            for line in output_lines:
                if target_partition in line:
                    break
            
            # Extract the required information
            parts = line.strip().split()
            total_space = parts[1]
            used_space = parts[2]
            available_space = parts[3]
            use_percentage = parts[4]
            mounted_on = parts[5]
            
            # Return structured data
            response = {
                "device": target_partition,
                "total_gb": total_space,
                "used_gb": used_space,
                "available_gb": available_space,
                "use_percentage": use_percentage,
                "mounted_on": mounted_on,
                "timestamp": datetime.now(timezone.utc).isoformat()
            }
            
            self.send_response(200)
            self.send_header('Content-Type', 'application/json')
            self.end_headers()
            self.wfile.write(json.dumps(response).encode())
            
        except subprocess.CalledProcessError as e:
            # Handle the case where the df command execution fails
            error = {
                "error": str(e),
                "timestamp": datetime.now(timezone.utc).isoformat()
            }
            self.send_response(500)
            self.send_header('Content-Type', 'application/json')
            self.end_headers()
            self.wfile.write(json.dumps(error).encode())
    
if __name__ == "__main__":
    server_address = ('', 8080)

📚 Documentation

Project Structure

1. disk_usage_server.py: The main implementation file of the MCP server.
2. requirements.txt: The Python dependency management file.
3. claude - config.txt: An example configuration file for Claude Desktop, used to specify the location and running parameters of the MCP server.

Learning Outcomes

Through this project, you can learn the following:

1. How to create a simple MCP server using Python.
2. How to integrate system commands into an MCP tool.
3. How to design a structured data output format for AI.
4. How to handle operating - system - specific details (such as partition information).
5. How to provide clear and understandable human - readable summary information.