Skip to main content
Glama
disk-space-mcp

disk-space-mcp

by fjmn2001

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.

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 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.

Available Tools

1 tool
check_disk_spaceCheck disk spaceA
Read-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

    A4.2/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool, there is no ambiguity. The tool's purpose is clearly distinct and well-described.

    Naming Consistency5/5

    The single tool name 'check_disk_space' follows a consistent verb_noun pattern and is descriptive, so no inconsistency exists.

    Tool Count3/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers