MCP Integration — StorageRadar

What is the MCP integration?

When you enable MCP in StorageRadar, the app runs a lightweight local server on 127.0.0.1. AI assistants that support the Model Context Protocol (like Claude Desktop) can connect to this server and query your disk analytics in real time.

The server is strictly read-only. It can answer questions like "what's using the most space?" or "what changed since last week?" — but it cannot delete files, move anything, or access file contents. Think of it as giving your AI a read-only dashboard of your disk, not access to your files.

The MCP endpoint is available in all tiers. Enabling it and querying data is free. Running actual cleanup based on AI recommendations requires the appropriate unlock tier in StorageRadar.

Setup guide

Getting your AI connected to StorageRadar takes under two minutes.

Open Integrations in StorageRadar

In the sidebar, click Integrations. You'll see the MCP section at the top of the screen.

Enable MCP (Read-Only)

Toggle Enable MCP (Read-Only) on. The status indicator will change to Server running. StorageRadar will show the local endpoint address and port.

Generate your access token

Click Generate Token. Keep this token private — it's the only credential your AI client needs. You can rotate it at any time to revoke the previous one.

Copy the config snippet and paste into your AI client

Click Copy Client Config Snippet. StorageRadar generates the correct config format for your AI client. Paste it into your client's MCP server configuration (see Config snippet below for details).

Run a scan first

Make sure you've run at least one scan in StorageRadar. The MCP tools work on indexed scan data — if there's no scan, tools like largest_query will return empty results.

Example prompts

Copy any prompt below and paste it into your AI assistant after connecting StorageRadar. The AI will call the appropriate MCP tools and explain the results in plain language.

Your AI can only explain and recommend. To actually clean up, open StorageRadar and use its guided workflow — AI analysis and human-controlled cleanup are kept separate by design.

01 Quick connection check

get_server_info

Check the StorageRadar MCP connection: show server version, API version, app version, and all available features.

You get: serverVersion, apiVersion, appVersion, features[] — confirms the connection is working.

02 Recent scan sessions

list_scan_sessions

Show my last 10 scan sessions, newest first. For each: date, root volume, total size in GB, total item count.

You get: A list of recent scans — pick a sessionId from here to use in follow-up queries.

03 Latest scan breakdown

list_scan_sessionsget_scan_session

Take the most recent scan session and show its details: top categories (Apps, Dev, Media, System, Other) and the size histogram. Explain where the space went.

You get: Per-category breakdown with a plain-language explanation of your disk usage structure.

04 Top 30 largest items

largest_query

For the most recent scan, show the top 30 largest items (files and folders), sorted from largest to smallest. Include size in GB and risk level for each.

You get: The heaviest consumers on your disk with sizes and risk labels — the fastest way to find what to review.

05 Top 20 largest folders (> 500 MB)

largest_query

For the most recent scan, show the top 20 largest folders only (groupBy=folder), minimum size 500 MB, sorted by size descending.

You get: The biggest folders — fast candidates for manual review in Finder.

06 Breakdown by file extension

largest_query

For the most recent scan, show the top 15 file types by total size grouped by extension. Which file types are taking the most space?

You get: Extension distribution — tells you whether it's videos, archives, build artifacts, or something else filling your disk.

07 User vs system breakdown

largest_query

For the most recent scan, show disk usage grouped by owner (groupBy=owner). What share of space is mine vs system? Explain the breakdown.

You get: User/system aggregates — a clear separation of "my data" vs macOS files.

08 List saved snapshots

list_snapshots

Show my last 20 disk snapshots: ID, date, label, and total size for each. Sort newest first.

You get: A snapshot list ready for comparison — note the IDs you want to compare with diff_snapshots.

09 Why did my disk grow this week?

list_snapshotsdiff_snapshots

Take the most recent snapshot and the snapshot closest to 7 days ago. Compare them by category (groupBy=category) and explain what grew the most.

You get: Delta by category (Apps/Dev/Media/System/Other) with a plain-language growth explanation and the biggest contributors.

10 What changed after updating Xcode?

list_snapshotsdiff_snapshots

Find the two snapshots closest to the date [insert date, e.g. 2026-02-15]. Compare them by extension and folder (two separate queries). Show the top growth items for each.

You get: Growth by folder and extension — often shows DerivedData, simulators, and Xcode caches as the main contributors.

11 Only large changes between two snapshots (> 1 GB)

diff_snapshots

Compare snapshots [baseId] and [compareId]. Show only changes larger than 1 GB (minDeltaBytes=1073741824), limit 100. Group by category.

You get: Only the significant changes — less noise, faster review of what actually moved the needle.

12 Dev caches: where is the biggest volume?

get_dev_cleanup_summary

Show the dev cleanup summary for the most recent scan. Sort profiles by size descending and highlight the top 5 with their size and risk level.

You get: Xcode, npm, Gradle, Docker, etc. profiles ranked by size — shows where the biggest cleanup potential is.

13 Dev caches prioritized by risk

get_dev_cleanup_summary

Show the dev cleanup summary and split all profiles into three groups: safe / caution / high risk. Give recommendations: what to clean first, what to check before cleaning, and what to leave alone.

You get: A risk-aware priority plan — safe caches to delete confidently, risky ones to verify first.

14 10-step manual cleanup plan

largest_queryget_dev_cleanup_summary

Based on the most recent scan and dev cleanup summary, create a 10-step manual cleanup plan. Start with the safest and largest candidates, end with items that need extra care before deleting.

You get: A numbered action plan — paste it into notes and work through it in StorageRadar step by step.

15 Check path privacy policy

largest_query

Show 10 items from largest_query (groupBy=item) for the most recent scan. For each path, note whether it looks generalized (e.g., ~/Library/Developer/…/*) or detailed. Does the current privacy policy seem to be working?

You get: A quick verification that your Path Privacy Policy setting is working as expected before sharing results.

16 Disk growth trend over 5 snapshots

list_snapshots

Take the last 5 snapshots and build a brief trend: total disk size on each date, total growth over the period, and average daily growth rate in MB/day.

You get: A mini timeline — tells you how fast your disk is filling up and whether growth is accelerating.

17 Find anomalous growth spikes

list_snapshotsdiff_snapshots

Compare the last 3 consecutive pairs of snapshots (oldest→middle, middle→newest). Find categories or folders where growth was sudden and unusually large compared to the other periods.

You get: Growth spike candidates with timestamps — pinpoints when and where something unexpectedly ballooned.

18 Executive summary

get_scan_sessiondiff_snapshotsget_dev_cleanup_summary

Give me a short executive summary of my Mac's storage: current total disk size, top 3 consumers by category, what grew since the last snapshot, and 5 safe cleanup recommendations ordered by size.

You get: A decision-ready summary — no excessive detail, just what you need to decide whether to clean and what to target first.

19 Full markdown report

get_scan_sessionlargest_querydiff_snapshotsget_dev_cleanup_summary

Build a markdown report for the most recent scan. Include: top categories, top 10 largest folders, top 10 file types by extension, dev cleanup summary sorted by size, and key changes between the two most recent snapshots.

You get: A ready-to-save markdown document — paste into Obsidian, Notion, or any notes app as a disk health report.

20 Verify MCP connection end-to-end

get_server_infotools/list

Verify my StorageRadar MCP connection end-to-end: initialize the session, list all available tools, and call get_server_info. Show what passed and what the server returned.

You get: A full health check — confirms the server is running, authenticated, and all 7 tools are available.

Available MCP tools

StorageRadar exposes seven read-only tools over MCP. Your AI client can call these automatically based on your question. All tools support cursor-based pagination and return stable, deterministic results.

get_server_info Diagnostics

Returns server version, API version, app version, and the list of enabled features. Useful for verifying the connection is working.

Returns serverVersion apiVersion appVersion features[]

list_scan_sessions Scans

Lists all scan sessions with their status, root volume, scope (full volume or custom folder), and summary stats. Supports filtering by date range and pagination.

Params cursor limit from to

Returns per session id createdAt rootVolume scope status totalBytes totalItems durationMs

get_scan_session Scans

Returns detailed metadata and aggregates for a specific scan session, including a breakdown of disk usage by top-level category (Apps, Developer, Media, System, Other).

Params id

Returns metadata categories[] histogram

largest_query Analysis

Returns the top-N largest items from a scan or snapshot, with flexible grouping. This is the most versatile tool — use it to find the biggest files, folders, extensions, or categories.

Params sessionId snapshotId pathPrefix groupBy minBytes cursor limit

groupBy options item folder extension owner category

Returns per entry key bytes items risk

list_snapshots Snapshots

Lists all saved disk snapshots in chronological order. Snapshots are captured manually from the Reports section and represent a point-in-time state of your disk.

Params cursor limit from to

Returns per snapshot id createdAt label rootScope totalBytes

diff_snapshots Snapshots

Compares two snapshots and returns what grew, shrank, appeared, or disappeared between them. Filter by minimum change size and group results by path, extension, or category.

Params baseId compareId groupBy minDeltaBytes cursor limit

Returns per entry key deltaBytes deltaItems direction notes

get_dev_cleanup_summary Dev Cleanup

Returns an aggregated summary of developer caches and build artifacts — Xcode DerivedData, CocoaPods, Gradle, Docker layers, npm modules, and more. Includes risk levels and hints. Read-only — no cleanup actions.

Params sessionId snapshotId cursor limit

Returns per profile profileId name bytes items riskLevel hints[]

Pagination limits

Default limit is 50, maximum is 200. All list tools return a cursor for fetching the next page. Results are always returned in a stable, deterministic order.

Security

Loopback only

The server binds to 127.0.0.1 exclusively. No LAN exposure, no internet access. Other devices on your network cannot reach it.

Token required

Every request must include your session token. Without it, the server rejects the request and logs the attempt. You can rotate the token at any time to revoke previous access.

Rate limited

Requests are rate-limited per token (default: 60 requests/min, configurable). This prevents runaway AI agents from hammering the local server.

Full audit log

Every tool call is logged locally to ~/Library/Application Support/StorageRadar/mcp-audit-log.json: timestamp, token ID, tool name, parameters, response size, latency, and any errors.

What the MCP endpoint cannot do

Delete or move any files
Read the contents of any file
Access the network or the internet
Call any tool not in the approved list
Execute or auto-apply any recommendations

Privacy & data minimization

StorageRadar follows a data minimization policy for MCP responses. By default, it returns generalized paths rather than exposing exact project names or personal directory names.

Default (recommended)

Generalized paths

Paths are abstracted at the category level. For example:

Instead of ~/Library/Developer/Xcode/DerivedData/MySecretApp-xyz123

Returns ~/Library/Developer/Xcode/DerivedData/*

This means your AI gets useful aggregate data without leaking specific project names or identifiers.

Optional

Raw paths, home redacted

Enable Raw paths (home redacted) in Integrations → Path Privacy Policy for more detailed paths. When enabled:

More specific paths are returned (useful for targeted diagnostics)
Your home directory is always replaced with ~
Long segments and ID-like strings are masked automatically

File contents are never returned in any mode. This is a hard constraint — the MCP server has no mechanism to read or transmit the contents of your documents, images, code, or any other files.

Config snippet

StorageRadar generates the correct config snippet for your AI client automatically — click Copy Client Config Snippet in the Integrations screen. Below is an example of what the snippet looks like for Claude Desktop.

The MCP server uses Streamable HTTP transport on port 7342 (protocol revision 2025-11-25). Your token goes in the Authorization header — no proxy, no stdio bridge needed.

Claude Desktop / any JSON-config client

Add the storageradar entry to the mcpServers object in your client's config file:

claude_desktop_config.json

{
  "mcpServers": {
    "storageradar": {
      "transport": "streamable_http",
      "url": "http://127.0.0.1:7342/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

Replace <YOUR_TOKEN> with the token from Integrations. StorageRadar fills in the correct values when you click Copy Client Config Snippet.

Claude Code (CLI)

If you use Claude Code in the terminal, register the server with one command:

Terminal

claude mcp add --transport http storageradar http://127.0.0.1:7342/mcp \
  --header "Authorization: Bearer <YOUR_TOKEN>"

After connecting, verify it works: ask your AI "Check the StorageRadar MCP connection" — it will call get_server_info and show server version and available features.

Rotating your token

Click Generate / Rotate Token in StorageRadar anytime to invalidate the current token. Update the Authorization header in your client's config afterward — any request with the old token returns 403 AUTH_INVALID immediately.