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_scanis safe - only scans, never deletesone_touch_cleanautomatically 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