# Disk Space Monitor — MCP Server

A small [Model Context Protocol](https://modelcontextprotocol.io) server that lets an AI assistant
inspect disk usage on the machine it is running on. Point Claude Desktop (or any MCP client) at it
and you can ask *"is my disk filling up?"* and get a real answer instead of a guess.

Cross-platform (Windows / macOS / Linux), no configuration files, no network access, no telemetry.

---

## Tools

| Tool | Arguments | What it does |
| --- | --- | --- |
| `check_disk_space` | `threshold: float = 50.0` | Scans every mounted partition and flags anything above the threshold. |
| `check_single_path` | `path: str`, `threshold: float = 50.0` | Detailed report for one path or drive, plus advice. |
| `disk_summary` | `threshold: float = 50.0` | One-line health verdict across all partitions. |

### Status levels

| Level | Trigger | Marker |
| --- | --- | --- |
| OK | below `threshold` | 🟢 |
| WARNING | at or above `threshold` (default 50%) | 🟠 |
| CRITICAL | at or above 90% | 🔴 |
| SKIPPED | unreadable or timed out | ⚪ |

---

## Example output

`disk_summary()`

```
🟢 ALL GOOD — All partitions below 50.0%. System is healthy.
```

`check_single_path("C:\\")`

```
💽  DISK USAGE: C:\
    Windows 11  │  2026-08-17 19:08:44  │  Threshold: 50.0%
─────────────────────────────────────────────────────────────────
  Status  : 🟠 WARNING
  Usage   : [██████████████░░░░░░░░] 63.4%
  Used    :    301.2 GB
  Free    :    173.8 GB
  Total   :    475.0 GB
─────────────────────────────────────────────────────────────────
⚠️  Above 50.0%. Consider archiving old files or clearing caches.
```

`check_disk_space(threshold=70)`

```
💽  DISK SPACE REPORT
    Windows 11  │  2026-08-17 19:08:44  │  Threshold: 70.0%
─────────────────────────────────────────────────────────────────
  🟢 OK        C:\  [NTFS]
           [██████████████░░░░░░░░] 63.4%
           Used     301.2 GB  │  Free     173.8 GB  │  Total     475.0 GB

  🔴 CRITICAL  D:\  [NTFS]
           [████████████████████░░] 92.7%
           Used     927.0 GB  │  Free      73.0 GB  │  Total    1000.0 GB
─────────────────────────────────────────────────────────────────
⚠️  1 critical, 0 warning:
   🔴 D:\ (92.7%)
```

---

## Requirements

- Python 3.10 or newer (developed on 3.12)
- [`mcp`](https://pypi.org/project/mcp/) and [`psutil`](https://pypi.org/project/psutil/)

## Installation

```bash
git clone https://github.com/<your-username>/disk-space-monitor.git
cd disk-space-monitor

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt
```

## Connecting it to Claude Desktop

Add the server to your Claude Desktop config file:

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

```json
{
  "mcpServers": {
    "disk-monitor": {
      "command": "/absolute/path/to/disk-space-monitor/.venv/bin/python",
      "args": ["/absolute/path/to/disk-space-monitor/main.py"]
    }
  }
}
```

On Windows the paths look like `C:/path/to/disk-space-monitor/.venv/Scripts/python.exe` and
`C:/path/to/disk-space-monitor/main.py`. Both paths must be absolute — the server is launched
directly, not through a shell.

Restart Claude Desktop afterwards. The three tools appear automatically, and you can ask things like:

> Is my disk filling up?
> Check drive D: and warn me if it's over 80%.
> Give me a one-line disk health summary.

## Running it standalone

```bash
python main.py
```

The server communicates over stdio using the MCP protocol, so running it directly just blocks
waiting for a client — that is expected, not a hang.

---

## How it works

**Partition discovery.** `psutil.disk_partitions(all=False)` lists real mounted partitions, then
pseudo-filesystems that commonly hang or carry no meaningful usage data are skipped:
`squashfs`, `tmpfs`, `devtmpfs`, `overlay`, `autofs`, and entries with no filesystem type.

**Timeout guard.** Each partition is read inside a daemon thread with a 0.5 second deadline. A
disconnected network drive or a sleeping external disk can make `shutil.disk_usage()` block for a
long time; if the deadline passes the partition is reported as `⚪ SKIPPED` and the scan moves on.
This keeps a single bad mount from freezing the whole tool call.

**Formatting.** Sizes render as GB below 1000 GB and TB above it. The usage bar is 22 characters
wide and clamped to that range, so malformed percentages cannot produce runaway output.

## Project structure

```
disk-space-monitor/
├── main.py            # the entire server — helpers + three tools
├── requirements.txt   # mcp, psutil
├── .gitignore
├── LICENSE
└── README.md
```

## Privacy

The server reads only local disk-usage figures — total, used, and free bytes per partition, plus
the OS name and version for the report header. It makes no network requests, writes no files,
reads no file contents, and stores nothing between calls.

## License

MIT — see [LICENSE](LICENSE).