Skip to main content
Glama
diskcleankit-mcp

diskcleankit-mcp

by namtran

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

Related MCP server: DiskSweep MCP

Installation

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

Available Tools

12 tools
get_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

    A4/5.0

    Scored across 12 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables an AI assistant to perform read-only scans of Windows drives and identify cleanup candidates, including caches, temporary files, and largest files.
      1
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      12
      MIT