DiskCleanKit MCP Server

MCP (Model Context Protocol) server that enables AI assistants like Claude to control DiskCleanKit's One Touch feature for Mac disk cleaning.

# Prerequisites

• macOS
• DiskCleanKit app installed
• Node.js v18+

# Installation

# # Via npm (Recommended)

npm install -g @vannamtran/diskcleankit-mcp

# # From Source

git clone https://github.com/namtran/diskcleankit-mcp
cd diskcleankit-mcp
npm install
npm run build

# Configuration

# # Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "diskcleankit": {
      "command": "npx",
      "args": ["@vannamtran/diskcleankit-mcp"]
    }
  }
}

Then restart Claude Desktop.

# # Claude Code (CLI)

claude mcp add - -transport stdio diskcleankit - - npx @vannamtran/diskcleankit-mcp

Or edit ~/.claude/settings.json:

{
  "mcpServers": {
    "diskcleankit": {
      "command": "npx",
      "args": ["@vannamtran/diskcleankit-mcp"]
    }
  }
}

# # Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-specific):

{
  "mcpServers": {
    "diskcleankit": {
      "command": "npx",
      "args": ["@vannamtran/diskcleankit-mcp"]
    }
  }
}

Or go to Cursor Settings → Tools & Integrations → New MCP Server.

# # VS Code (GitHub Copilot)

Add to your settings.json:

{
  "mcp.servers": {
    "diskcleankit": {
      "command": "npx",
      "args": ["@vannamtran/diskcleankit-mcp"]
    }
  }
}

# # Other MCP Clients

| Client | Config File |
|- -- -- -- -|- -- -- -- -- -- --|
| Cline | VS Code extension settings |
| Windsurf | ~/.windsurf/mcp.json |
| Zed | ~/.config/zed/settings.json |
| Continue | ~/.continue/config.json |

Use the same configuration structure:

{
  "mcpServers": {
    "diskcleankit": {
      "command": "npx",
      "args": ["@vannamtran/diskcleankit-mcp"]
    }
  }
}

# # Ollama (via mcphost)

Ollama doesn't natively support MCP, but you can use mcphost:

pip install mcphost
mcphost -m ollama:qwen2.5 - -config config.json

# # Unsupported

• ChatGPT: No native MCP support

# Available Tools

| Tool | Description |
|- -- -- -|- -- -- -- -- -- --|
| one_touch_scan | Scan for junk files (safe, no deletion) |
| one_touch_clean | Recommended - Scan AND clean junk files automatically |
| get_disk_status | Check disk space and health status |
| get_cleanable_estimate | Estimate cleanable space by category |
| get_cleaning_history | View past cleaning sessions |

# What Gets Cleaned

one_touch_clean automatically scans and cleans safe items only:

| Category | Description |
|- -- -- -- -- -|- -- -- -- -- -- --|
| System Caches | macOS system cache files |
| Application Caches | App-generated cache files |
| Application Logs | Old log files from apps |
| Browser Caches | Safari, Chrome, Firefox cache |

These are all safe to delete and will be regenerated by the system/apps as needed.

# Usage Examples

Once configured, ask your AI assistant:

• "Scan my Mac for junk files" → one_touch_scan
• "Clean up my Mac" → one_touch_clean
• "How much disk space do I have?" → get_disk_status
• "What can be cleaned?" → get_cleanable_estimate
• "Show my cleaning history" → get_cleaning_history

# How It Works

AI Assistant → MCP Server → URL Scheme → DiskCleanKit App
                   ↑                            ↓
              JSON Response ← Temp File ← Response

1. AI calls MCP server tools
2. MCP server triggers DiskCleanKit via diskcleankit:// URL scheme
3. DiskCleanKit processes request and writes response to /tmp/diskcleankit_mcp_response.json
4. MCP server reads response and returns to AI

# Security

• one_touch_scan is safe - only scans, never deletes
• one_touch_clean automatically scans AND cleans safe items (caches & logs only)
• Only cleans regenerable files - no personal data or documents are ever touched
• All processing happens locally on your Mac
• No data sent to external servers

Note: one_touch_clean is safe to run directly - it only removes system/app caches and logs that will be regenerated automatically.

# Troubleshooting

# # "Timeout waiting for response"

• Ensure DiskCleanKit app is installed
• Try opening DiskCleanKit manually first

# # Server not appearing in Claude

• Verify config path is correct
• Restart Claude Desktop after config changes
• Check Claude logs for errors

# License

MIT

# Links

• DiskCleanKit App
• MCP Protocol