disk-space-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@disk-space-mcp check disk space on /projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
disk-space-mcp
A small Model Context Protocol server that
reports and validates free disk space. It exposes a single read-only tool,
check_disk_space, backed by Node's fs.statfs — no shell-outs to df, no
runtime dependencies beyond the MCP SDK and Zod.
Tool: check_disk_space
Reports total / used / available space for the filesystem that contains a path, and validates it against optional free-space thresholds.
Argument | Type | Default | Description |
| string | home directory | Any path; stats apply to the filesystem containing it. |
| number | — | If available space is below this many GiB, |
| number |
| If available space is below this percentage, |
It returns both a human-readable text block and structuredContent:
{
"path": "/Users/you",
"totalBytes": 494384795648,
"usedBytes": 312000000000,
"freeBytes": 182000000000,
"availableBytes": 175000000000,
"usedPercent": 63.11,
"availablePercent": 35.4,
"status": "ok",
"message": "OK: 163 GiB available of 460 GiB (35.4% free, 63.11% used) on /Users/you."
}availableBytes (POSIX bavail) is the space actually usable by your user and
is the value the thresholds check; freeBytes (bfree) additionally counts
space reserved for root.
Related MCP server: disk-clean-mcp
Develop
npm install
npm run build # tsc -> dist/
npm test # vitest: pure-logic unit tests + in-memory protocol tests
npm run typecheck # tsc --noEmit
npm run smoke # build first, then spawn the server and call the tool over stdioRegister with Claude Code
npm run build
claude mcp add disk-space --scope user -- node /ABSOLUTE/PATH/TO/disk-space-mcp/dist/index.jsOr add it manually to an MCP client config:
{
"mcpServers": {
"disk-space": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/disk-space-mcp/dist/index.js"]
}
}
}Design notes
Layered for testability.
diskSpace.tsis a pure module (byte math, thresholds, formatting) with no I/O, unit-tested in isolation.getDiskStats.tsis the thinfs.statfsadapter, injected intocreateServer()so the protocol wiring can be tested end-to-end against an in-memory transport with fabricated stats.stdio-safe. All diagnostics go to stderr; stdout carries only JSON-RPC.
Read-only and shell-free. The tool only reads filesystem capacity via
statfs; it never reads file contents and never invokes a shell, so there is no command-injection surface. Paths are resolved to absolute and failures (missing path, permission denied) return a cleanisErrorresult.Unit semantics. Byte counts use
frsizewhen available (Node ≥ 24.16), falling back tobsizeon older runtimes. Sizes are formatted with binary (IEC) units — KiB / MiB / GiB.
Security
Read-only, shell-free. The only side effect is
fs.statfs. There is nochild_process/exec/spawnanywhere, so there is no command-injection surface, andstatfsexposes filesystem capacity only — never file contents.Input is validated at the boundary. The
pathargument is length-capped and rejected if it contains control characters (NUL, ESC, CR, …), which both neutralizesstatfs's silent null-byte truncation and prevents control/ANSI sequences from being reflected into tool output that a terminal or agent later renders.minFreeGb/minFreePercentare bounded and must be finite.No information leak on error. Failures return a clean
isErrorresult with an errno code (e.g.ENOENT) rather than raw runtime internals; full error detail is logged to stderr only.stdio-only. Only
StdioServerTransportis instantiated. The MCP SDK transitively pulls in an HTTP/auth stack that this server never uses; since consumers only run the stdio binary, those code paths are never reached. For a hardened install,npm ci --ignore-scriptsis safe (no runtime dependency needs an install script). CI gates production dependencies withnpm audit --omit=dev --audit-level=high.
License
MIT — see LICENSE.
Available Tools
1 toolcheck_disk_spaceCheck disk spaceARead-onlyIdempotent
Report total, used, and available disk space for the filesystem containing a path, and validate it against optional free-space thresholds. Read-only: reads filesystem stats via statfs, never runs a shell. Returns a status of "ok" or "warning".
Inputs: path, minFreeGb, minFreePercent. Returns: path, totalBytes, usedBytes, freeBytes, +5 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool, there is no ambiguity. The tool's purpose is clearly distinct and well-described.
The single tool name 'check_disk_space' follows a consistent verb_noun pattern and is descriptive, so no inconsistency exists.
One tool is borderline thin for a file system utility. While it serves a focused purpose, users might expect additional capabilities like listing mounts or checking multiple paths.
The tool provides basic disk space checking for a single path but lacks coverage for multiple filesystems, threshold management, or detailed usage reports. Notable operations are missing.
Maintenance
Related MCP Connectors
MCP deployment checks: required tools, schema drift and verifiable receipts. Free preflight.
Read-only Linux server and Docker monitoring for AI assistants: CPU, memory, disk, network.
Validate JSON, YAML, XML and CSV with exact line/column errors and silent-corruption warnings.
Search reviewed free tools, submit for review, run launch checks, and find launch directories.
Related MCP Servers
- FlicenseBqualityDmaintenanceProvides tools to check disk usage and search files by keyword on the local system.2-
- AlicenseBqualityDmaintenanceEnables read-only analysis of local disk usage to identify cleanup targets by size, type, recency, and duplicates.613 npm1MIT
- AlicenseAqualityCmaintenanceEnables real-time Windows storage analysis, deep folder scanning, safety tiering, and protected cleanup operations through natural language.41MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to check disk usage on the host machine, providing real-time reports on partition health, warnings, and critical alerts across Windows, macOS, and Linux.MIT