Sweep MCP

What sweep-mcp MCP server does

The sweep-mcp MCP server exposes the sweep directory-reclamation functionality through MCP. It helps an agent identify generated or reproducible directories that can consume local disk space, including examples such as node_modules, .venv, target, and __pycache__. The server does not provide arbitrary path deletion: an agent must first scan an allowed location, then refer to the resulting findings by ID.

The available tools are:

• list_targets reports the directory types the server recognizes and the command associated with regenerating each one.
• scan searches beneath a path inside the configured roots and returns finding IDs, paths, sizes, and regeneration commands. It is read-only.
• reclaim accepts finding IDs and can delete those findings. It performs a dry run unless confirm="delete" is supplied exactly.

How it works

At startup, the server receives one or more root directories through --root. These roots form a fixed allowlist; no root means requests are refused, and the agent cannot expand or inspect beyond the configured locations. Paths are resolved before containment checks, which addresses parent-directory traversal and symlink escape attempts.

Deletion is separated from discovery. scan creates random, non-sequential IDs, while reclaim accepts IDs rather than filesystem paths. Immediately before deletion, each selected finding is checked again to confirm that it remains inside an allowed root, is still a directory, is not a link, and still has the expected marker. The implementation reduces the scan-to-delete race but does not eliminate the final filesystem race.

The tools include MCP annotations: list_targets and scan are marked read-only, while reclaim is marked destructive. Descriptions are static rather than assembled from filesystem content.

Setup and configuration

Install the package with:

pip install sweep-mcp

For a source checkout, use pip install -e .. Configure the sweep-mcp MCP server as a stdio process and provide every permitted location explicitly:

{
  "mcpServers": {
    "sweep": {
      "command": "sweep-mcp",
      "args": ["--root", "/home/you/code", "--root", "/home/you/work"]
    }
  }
}

There is no default root. The chosen roots determine the server's effective filesystem scope, so they should be limited to directories where reclaiming generated content is appropriate.

Limitations and notes

The safeguards do not sandbox the process, validate the administrator's root choice, or authenticate the client. Running with a broad root, including /, gives the process a correspondingly broad deletion scope. A client that performs a valid scan and confirmation can request the deletion represented by that finding.

On Python 3.11, Windows junction detection is less complete because os.path.isjunction is unavailable; detection falls back to symlink handling. The server also cannot completely close the interval between revalidation and deletion because the underlying removal operation does not portably retain directory file descriptors across the operation.

The sweep-mcp MCP server is tested on Linux and Windows, with symlink-related tests requiring suitable Windows permissions or developer mode. It is distributed under the MIT license and supports Python 3.11 through 3.13 as indicated by the project metadata.