diskcleankit-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@diskcleankit-mcp scan my Mac for junk files"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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+
Related MCP server: DiskSweep MCP
Installation
Via npm (Recommended)
npm install -g @vannamtran/diskcleankit-mcpFrom Source
git clone https://github.com/namtran/diskcleankit-mcp
cd diskcleankit-mcp
npm install
npm run buildConfiguration
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-mcpOr 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 |
|
Zed |
|
Continue |
|
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.jsonUnsupported
ChatGPT: No native MCP support
Available Tools
Tool | Description |
| Scan for junk files (safe, no deletion) |
| Recommended - Scan AND clean junk files automatically |
| Check disk space and health status |
| Estimate cleanable space by category |
| 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 ← ResponseAI calls MCP server tools
MCP server triggers DiskCleanKit via
diskcleankit://URL schemeDiskCleanKit processes request and writes response to
/tmp/diskcleankit_mcp_response.jsonMCP 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
Links
Available Tools
12 toolsget_cleanable_estimateA
Estimate how much space can be cleaned by One Touch Clean. Returns breakdown by category (caches, logs, Xcode data, trash, etc.).
Inputs: no named parameters.
get_cleaning_historyA
Get history of past cleaning sessions including total space freed, number of sessions, and details of recent cleans. Use this to answer 'how much did I clean last week?'
Inputs: limit.
get_dev_cachesB
Analyze developer tool caches: Xcode derived data, iOS simulators, npm, Yarn, CocoaPods, Homebrew, Gradle, Maven, Docker. Use this to answer 'clean all my dev caches' or help developers specifically.
Inputs: no named parameters.
get_disk_statusA
Get current disk space status including total space, free space, used space, usage percentage, and health status (healthy/warning/critical).
Inputs: no named parameters.
get_large_filesA
Find large files on the Mac. Returns a list of the biggest files with their paths, sizes, and types. Use this to answer 'what are these large files?' or 'find big files'.
Inputs: min_size_mb, limit.
get_storage_breakdownA
Get detailed storage breakdown by category (Documents, Downloads, Developer, Caches, etc.). Use this to answer 'What's eating my disk space?' with specific category sizes.
Inputs: no named parameters.
one_touch_cleanA
Run DiskCleanKit One Touch Clean - automatically cleans the items found by the previous scan. WARNING: This deletes files immediately without confirmation. Always run one_touch_scan first and get user approval before calling this.
Inputs: no named parameters.
one_touch_scanA
Run DiskCleanKit One Touch Scan - automatically scans your Mac for junk files, caches, logs, and system debris. Shows what can be cleaned WITHOUT deleting anything. Always run this first before cleaning.
Inputs: no named parameters.
show_cleaning_historyA
Open DiskCleanKit's Cleaning History screen. Shows past cleaning sessions with charts and statistics. Use this when user wants to visually review their cleaning history.
Inputs: no named parameters.
show_dashboardA
Open DiskCleanKit's main Dashboard. Shows overview of disk health, quick actions, and recommendations. Use this as a general entry point to show the app.
Inputs: no named parameters.
show_disk_managerA
Open DiskCleanKit's Disk Manager screen and auto-scan the system disk. Shows visual storage breakdown with charts. Use this when user wants to SEE their disk usage, or for first-time demos.
Inputs: no named parameters.
show_one_touchA
Open DiskCleanKit's One Touch Clean screen. Brings app to front for user interaction. Use this when user wants to manually control the cleaning process.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Most tools have distinct purposes: queries (get_*), actions (one_touch_*), and UI (show_*). However, get_cleaning_history and show_cleaning_history could be confused, as both relate to cleaning history but one returns data and the other opens a screen.
Tool names follow a consistent pattern: 'get_' for data retrieval, 'one_touch_' for automated actions, and 'show_' for opening UI screens. The only minor inconsistency is the pair 'get_cleaning_history' vs 'show_cleaning_history', which differ only by prefix but could still cause ambiguity.
With 12 tools, the set is well-scoped for a disk cleanup utility. It covers scanning, cleaning, detailed analysis, and UI navigation without being overwhelming or too sparse.
The toolset covers key workflows: scan, clean, analyze, and view. However, it lacks granular control (e.g., cleaning only specific categories) and a rollback feature, which are minor gaps for the intended domain.
Maintenance
Related MCP Connectors
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Scan websites and code for security, performance and SEO issues from your AI assistant.
Manage cookie banners, run cookie scans and check GDPR/CCPA compliance from your AI assistant.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables natural-language management of macOS disk cleanup by scanning large files, AI model weights, and caches, identifying duplicates, and safely moving files to Trash or permanently deleting them with confirmation.MIT
- AlicenseNot gradedqualityCmaintenanceEnables an AI assistant to measure macOS disk usage, investigate unfamiliar files and folders, identify cleanup candidates, and prepare numbered cleanup proposals that move approved items to the Trash only after server-side path checks.16 npm1MIT
- AlicenseAqualityCmaintenanceEnables an AI assistant to perform read-only scans of Windows drives and identify cleanup candidates, including caches, temporary files, and largest files.11MIT
- AlicenseAqualityCmaintenanceEnables AI assistants to scan a Mac for reclaimable disk space and safely move selected items to the Trash, with dry-run defaults, protected paths, and confirmation before permanent deletion.12MIT