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

AI calls MCP server tools
MCP server triggers DiskCleanKit via diskcleankit:// URL scheme
DiskCleanKit processes request and writes response to /tmp/diskcleankit_mcp_response.json
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

diskcleankit-mcp

Documentation