# Disk Insights MCP

**Ask Claude Desktop "what's eating my disk space?" — and get a real answer.**

A tiny, **read-only** [Model Context Protocol](https://modelcontextprotocol.io) server.
It reports your largest files and most bloated folders. It never deletes, moves, or
modifies anything, and wide scans are **time-bounded** so they return useful results
instead of hanging.

Runs 100% locally. Nothing leaves your machine.

---

## What it does

| Tool | What you ask Claude | What you get |
|------|--------------------|--------------|
| `largest_files` | "What are the biggest files in my Downloads?" | Top N files by size |
| `folder_sizes` | "Which folders in my home dir are biggest?" | Sub-folders ranked by total size |
| `disk_usage` | "How full is my disk?" | Total / used / free for the volume |

All read-only. All offline.

---

## Install (2 minutes)

**Requirements:** Python 3.10+ and the Claude Desktop app.

```bash
pip install "mcp[cli]"
```

Download `disk_insights_mcp.py` from this repo, then add it to your Claude Desktop
config:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```jsonc
{
  "mcpServers": {
    "disk-insights": {
      "command": "python3",
      "args": ["/full/path/to/disk_insights_mcp.py"]
    }
  }
}
```

Restart Claude Desktop. Then just ask: *"What's taking up space in my Downloads folder?"*

A ready-to-edit `claude_desktop_config.example.json` is included.

---

## Why read-only?

Disk cleanup tools that can delete files are exactly the tools you don't want an LLM
driving unsupervised. This server only *reports*. You stay in control of what to remove.

---

## Want the rest?

Disk Insights is one server from the **MCP Starter Kit** — a set of local-first servers
for Claude Desktop, all MIT licensed:

- **Doc Search** — index a folder and search across everything, including the text
  inside PDFs and DOCX, fully offline (SQLite FTS5, no gigabyte model to download).
- **Obsidian Vault** — read/write/search/link notes in a local Obsidian vault.
- **Git Companion** — status, diffs, log, blame, and drafts real commit messages
  (commits require explicit confirm, never pushes).
- Plus File Manager, Web Scraper, SQLite, PDF Export and Notes in the original kit.

One-click installers for macOS/Linux/Windows, clean uninstaller, full docs:
**https://kuhnrichard.gumroad.com/l/kpllrc**

Everything is MIT — you can always build your own from servers like this one.

---

## License

MIT © Richard Kuhn — [blog.kuhn.or.at](https://blog.kuhn.or.at)