cacheout-mcp

MCP server for macOS disk cache management — lets AI agents free disk space on demand.

Why

When you run AI agents (OpenClaw, Claude Code, etc.) on a Mac Mini or any macOS machine, disk pressure can silently degrade performance. Swap thrashing, failed builds, Docker OOM — all from running out of space that's locked up in developer caches.

cacheout-mcp gives your agent a set of tools to detect and fix disk pressure in real-time:

Agent detects 2 GB free → calls cacheout_smart_clean(target_gb=15) → 15 GB freed in 3 seconds

Related MCP server: FGD Fusion Stack Pro

Three Execution Modes

Mode is auto-detected at startup (socket → app → standalone). Override with CACHEOUT_MODE=standalone or CACHEOUT_MODE=app.

Install

# From PyPI (when published)
pip install cacheout-mcp

# From source
cd cacheout-mcp
pip install -e .

MCP Configuration

Claude Code / Claude Desktop

Add to ~/.claude/claude_desktop_config.json or your project's .mcp.json:

{
 "mcpServers": {
 "cacheout": {
 "command": "cacheout-mcp",
 "env": {}
 }
 }
}

OpenClaw / Custom Agents

{
 "mcpServers": {
 "cacheout": {
 "command": "python",
 "args": ["-m", "cacheout_mcp.server"],
 "env": {
 "CACHEOUT_MODE": "standalone"
 }
 }
 }
}

With uv (no install needed)

{
 "mcpServers": {
 "cacheout": {
 "command": "uvx",
 "args": ["cacheout-mcp"]
 }
 }
}

Tools

cacheout_get_disk_usage

Check current disk space. No parameters.

→ {"total": "500.1 GB", "free": "23.4 GB", "used_percent": 95.3}

cacheout_scan_caches

Scan all cache directories and report sizes. Optional filters:

• categories: List of slugs to scan (omit for all)

• min_size_mb: Only show categories above this size

→ {"total_cleanable": "45.2 GB", "categories": [{"slug": "xcode_derived_data", "size_human": "15.0 GB", ...}]}

cacheout_clear_cache

Clear specific categories by slug. Requires explicit category list.

• categories: Required list of slugs

• dry_run: Preview without deleting

← {"categories": ["xcode_derived_data", "homebrew_cache"], "dry_run": false}
→ {"total_freed": "18.2 GB", "results": [...]}

cacheout_smart_clean

The primary tool for agents. Specify how much space you need; it clears safest caches first.

• target_gb: Required — how many GB to free

• dry_run: Preview mode

• include_caution: Include Docker and other high-risk categories

• free_memory: Also run memory purge after disk cleanup (adds memory_freed, purge_result to response)

← {"target_gb": 10.0}
→ {"target_met": true, "total_freed_human": "12.3 GB", "disk_after": {"free_gb": 17.5}}

cacheout_status

Server status, mode, and available categories.

cacheout_get_memory_stats

Check RAM, swap, memory pressure, and memory tier. No parameters.

→ {"total_physical_mb": 16384.0, "memory_tier": "comfortable", "estimated_available_mb": 6096.0, ...}

cacheout_get_process_memory

List top memory-consuming processes. Optional top_n and sort_by parameters. Returns envelope: {mode, capabilities, data: {processes, count, sort_by_applied}, partial}.

cacheout_get_compressor_health

Check macOS memory compressor ratio, compression/decompression rates, and thrashing detection. No parameters. Returns envelope: {mode, capabilities, data: {compressor_ratio, thrashing, ...}, partial}.

cacheout_memory_intervention

Run memory interventions. Required parameters:

• intervention_name: Canonical name (e.g., "purge")

• confirm: false for dry-run preview, true to execute

Returns envelope: {mode, capabilities, data: {dry_run, intervention, ...}, partial}.

cacheout_system_health

Combined disk + memory + alert health check with a 0-100 score. No parameters. In socket mode, fetches from daemon. In standalone, computes locally.

cacheout_check_alerts

Read watchdog alerts (near-zero cost file read). Optional acknowledge parameter.

cacheout_get_recommendations

Get predictive memory/disk recommendations. Socket mode includes trend-based types (exhaustion_imminent, compressor_degrading). Standalone returns snapshot types only.

cacheout_configure_autopilot

Validate and apply autopilot/watchdog configuration. Required config parameter (dict with version, enabled, optional rules/webhook/telegram). This is a write/validate/apply tool.

Cache Categories (23 total)

Smart Clean Priority

When smart_clean is called, categories are cleaned in this order:

1. Safe categories, sorted by clean_priority (build artifacts first)

2. Review categories (browser caches, device support)

3. Caution categories (Docker) — only if include_caution=true

Stops as soon as target_gb is freed.

Environment Variables

Adding the CLI to Cacheout.app

If you maintain the Cacheout Swift app, add the CLIHandler.swift file to your Sources and update CacheoutApp.swift to check CLIHandler.shouldHandleCLI() on init. This enables Cacheout --cli scan, Cacheout --cli clean, etc. for app-mode integration.

License

MIT

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• cacheout_check_alertsA
• cacheout_clear_cacheA
• cacheout_configure_autopilotA
• cacheout_get_compressor_healthA
• cacheout_get_disk_usageA
• cacheout_get_memory_statsA
• cacheout_get_process_memoryA
• cacheout_get_recommendationsA