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
path	string	home directory	Any path; stats apply to the filesystem containing it.
minFreeGb	number	—	If available space is below this many GiB, status becomes "warning".
minFreePercent	number	10	If available space is below this percentage, status becomes "warning".

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.

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 stdio

Register with Claude Code

npm run build
claude mcp add disk-space --scope user -- node /ABSOLUTE/PATH/TO/disk-space-mcp/dist/index.js

Or 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.ts is a pure module (byte math, thresholds, formatting) with no I/O, unit-tested in isolation. getDiskStats.ts is the thin fs.statfs adapter, injected into createServer() 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 clean isError result.
• Unit semantics. Byte counts use frsize when available (Node ≥ 24.16), falling back to bsize on 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 no child_process/exec/spawn anywhere, so there is no command-injection surface, and statfs exposes filesystem capacity only — never file contents.
• Input is validated at the boundary. The path argument is length-capped and rejected if it contains control characters (NUL, ESC, CR, …), which both neutralizes statfs's silent null-byte truncation and prevents control/ANSI sequences from being reflected into tool output that a terminal or agent later renders. minFreeGb / minFreePercent are bounded and must be finite.
• No information leak on error. Failures return a clean isError result with an errno code (e.g. ENOENT) rather than raw runtime internals; full error detail is logged to stderr only.
• stdio-only. Only StdioServerTransport is 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-scripts is safe (no runtime dependency needs an install script). CI gates production dependencies with npm audit --omit=dev --audit-level=high.

License

MIT — see LICENSE.