Diskcleankit Mcp

DiskCleanKit MCP Server

[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-mcpcd diskcleankit-mcpnpm installnpm 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

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 mcphostmcphost -m ollama:qwen2.5 --config config.json

Unsupported

• ChatGPT: No native MCP support

Available Tools

What Gets Cleaned

one_touch_clean automatically scans and cleans safe items only:

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