DiskCleanKit

npm version

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