Back to StorageRadar
Integrations

MCP Integration

Let your AI assistant query StorageRadar analytics directly through a secure, local, read-only endpoint on your Mac. No cloud. No file access. You stay in control.

Read-only 127.0.0.1 only Token-authenticated No file contents No deletions

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 Model Context Protocol 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 is using the most space or what changed since last week, but it cannot delete files, move anything, or access file contents.

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

Setup guide

Getting your AI connected to StorageRadar takes under two minutes.

1

Open Integrations in StorageRadar

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

2

Enable MCP (Read-Only)

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

3

Generate your access token

Click Generate Token. Keep this token private. You can rotate it at any time to revoke the previous one.

4

Copy the config snippet and paste it 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.

5

Run a scan first

Make sure you have run at least one scan in StorageRadar. The MCP tools work on indexed scan data, so an empty scan history means 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.
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.
A list of recent scans. Pick a sessionId from here for follow-up queries.
03 Latest scan breakdown
list_scan_sessionsget_scan_session
Take the most recent scan session and show its details: top categories and the size histogram. Explain where the space went.
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, sorted from largest to smallest. Include size in GB and risk level for each.
The heaviest consumers on your disk with sizes and risk labels.
05 Top 20 largest folders
largest_query
For the most recent scan, show the top 20 largest folders only, minimum size 500 MB, sorted by size descending.
The biggest folders ready 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?
Extension distribution so you can see whether videos, archives, build artifacts, or something else is filling your disk.
07 User vs system breakdown
largest_query
For the most recent scan, show disk usage grouped by owner. What share of space is mine versus system? Explain the breakdown.
User and system aggregates for a clear separation of your data versus 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.
A snapshot list ready for comparison.
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 and explain what grew the most.
Category deltas with a plain-language growth explanation.
10 What changed after updating Xcode?
list_snapshotsdiff_snapshots
Find the two snapshots closest to the date 2026-02-15. Compare them by extension and folder in separate queries. Show the top growth items for each.
Growth by folder and extension, often showing DerivedData, simulators, and Xcode caches.
11 Only large changes between two snapshots
diff_snapshots
Compare snapshots [baseId] and [compareId]. Show only changes larger than 1 GB, limit 100. Group by category.
Only the significant changes with less noise.
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.
Xcode, npm, Gradle, Docker, and other profiles ranked by size.
13 Dev caches prioritized by risk
get_dev_cleanup_summary
Show the dev cleanup summary and split all profiles into safe, caution, and high risk. Recommend what to clean first, what to check before cleaning, and what to leave alone.
A risk-aware priority plan.
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 and end with items that need extra care.
A numbered action plan you can work through in StorageRadar.
15 Check path privacy policy
largest_query
Show 10 items from largest_query for the most recent scan. For each path, note whether it looks generalized or detailed. Does the current privacy policy seem to be working?
A quick verification that your Path Privacy Policy setting is working as expected.
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.
A mini timeline showing how fast your disk is filling up.
17 Find anomalous growth spikes
list_snapshotsdiff_snapshots
Compare the last 3 consecutive pairs of snapshots. Find categories or folders where growth was sudden and unusually large compared to the other periods.
Growth spike candidates with timestamps.
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.
A decision-ready summary without excessive detail.
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.
A ready-to-save markdown document for notes or incident tracking.
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.
A full health check confirming the server is running, authenticated, and ready.

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 serverVersionapiVersionappVersionfeatures[]
list_scan_sessions Scans

Lists all scan sessions with their status, root volume, scope, and summary stats. Supports filtering by date range and pagination.

Params cursor limit from to
Returns per session idcreatedAtrootVolumescopestatustotalBytestotalItemsdurationMs
get_scan_session Scans

Returns detailed metadata and aggregates for a specific scan session, including disk usage by top-level category.

Params id
Returns metadatacategories[]histogram
largest_query Analysis

Returns the top-N largest items from a scan or snapshot with flexible grouping. Use it to find the biggest files, folders, extensions, or categories.

Params sessionId snapshotId pathPrefix groupBy minBytes cursor limit
groupBy options itemfolderextensionownercategory
Returns per entry keybytesitemsrisk
list_snapshots Snapshots

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

Params cursor limit from to
Returns per snapshot idcreatedAtlabelrootScopetotalBytes
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 keydeltaBytesdeltaItemsdirectionnotes
get_dev_cleanup_summary Dev Cleanup

Returns an aggregated summary of developer caches and build artifacts. Includes risk levels and hints. Read-only only, with no cleanup actions.

Params sessionId snapshotId cursor limit
Returns per profile profileIdnamebytesitemsriskLevelhints[]

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. 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 with timestamp, token ID, tool name, parameters, response size, latency, and 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 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 for Claude Desktop.

The MCP server uses Streamable HTTP transport on port 7342. Your token goes in the Authorization header. No proxy or stdio bridge is 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:

Claude Code (CLI) 
claude mcp add --transport http storageradar http://127.0.0.1:7342/mcp \
  --header "Authorization: Bearer <YOUR_TOKEN>"

After connecting, verify it works by asking your AI to 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.