Disk Space Monitor — MCP Server

A small Model Context Protocol 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 and psutil

Installation

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

{
  "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

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.