shutil MCP server
Commit Nov 12, 2026Provides asynchronous file system utilities with structured JSON output and safety features like soft-deletion and jail support for AI agents.
Also known as cwt/shutil-mcp
- Stars
- 0
- Tools
- 17
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 12, 2026
- License
- MIT
What is shutil MCP?
shutil provides asynchronous file system utilities with structured JSON output and safety features like soft-deletion and jail support for AI agents. It exposes 17 tools, such as restore, empty_trash, gc_trash.
Summary generated from the project's README
About shutil MCP server
shutil-mcp provides a suite of asynchronous file system utilities specifically designed for AI agents. Unlike standard shell tools that return raw text, this server delivers structured JSON output to ensure models can parse data accurately. It supports multiple transport methods including standard input/output, SSE, and streamable HTTP, making it compatible with both local setups and web-based clients like llama.cpp WebUI.
Security is a core focus of this implementation. Developers can use the jail feature to restrict all file operations to a specific directory tree. The server includes safety mechanisms such as zip-slip protection for unpacking archives and a soft-delete system where the rm tool moves files to a .trash folder instead of permanent deletion. For administrative tasks, tools like chmod and chown provide automatic rollbacks and return previous states to allow for easy undo operations. This makes it a reliable choice for developers building agents that require direct file system interaction without risking accidental data loss.
What you can do with it
- 1Safe file deletion and recoveryAsk the agent to remove a file while ensuring it can be restored from a trash folder if needed.
- 2Secure directory restricted accessConfigure the server to limit an AI agent to a specific project folder to prevent unauthorized file access.
- 3Reversible permission managementInstruct the agent to change file ownership or permissions with the ability to revert changes if a failure occurs.
- 4Safe archive extractionHave the agent unpack a compressed file while protecting the system from directory traversal attacks.
Written from the project's README. Every use case is checked against a quote from it.
shutil MCP tools 17
Detected from the READMErestoreempty_trashgc_trashmkdirtouchchmodchownstatdisk_usagewhichcatglob
Show all 17 toolsShow fewer tools
greptreemake_archiveunpack_archiveget_archive_formats
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecwt/shutil-mcp is public and reachablegithub.com/cwt/shutil-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/cwt/shutil-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model17 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubshutil-mcp
An MCP server providing asynchronous shell utilities using aioshutil.
This project offers a set of file system tools designed for AI agents, returning structured JSON output instead of raw text. This allows for more precise and direct consumption of file system data by AI models.
Features
- Asynchronous Operations: Leverages
aioshutiland thread executors for non-blocking file system tasks. - JSON Output: All tools return minified JSON, optimized for AI agents.
- Tool Annotations & Hints: Declares
readOnlyHint,destructiveHint,idempotentHint, andopenWorldHinton every tool for agent safety and host warnings. - Jail Support: Restrict file system access to a specific directory tree for security.
- Verification & Integrity:
mvandcpverify destination data before unlinking or finalizing, preventing data loss on partial failures. - Reversible Mutations & Undo:
chmodandchownreturn previous modes and ownership to facilitate immediate undo/redo, with automatic rollback on failure. - Safe Deletion & Recovery:
rmalways soft-deletes into.trash(never permanently deletes) and reports trash size and storage usage;restorerecovers items,gc_trashcollects expired items, andempty_trashpurges the trash. - Zip-Slip Protection:
unpack_archivevalidates all archive member paths against directory traversal / zip-slip attacks. - Detailed Metadata: Tools like
lsandstatprovide comprehensive information (size, mtime, mode, owner, etc.). - HTTP Transport Support: Includes built-in support for SSE and Streamable HTTP transports.
Available Tools
ls: List directory contents with detailed metadata.cp: Copy files or directories recursively with verification and overwrite protection.mv: Move/rename files or directories with safe pre-removal verification.rm: Soft-delete by moving to.trash; never permanently deletes and reports trash statistics.restore: Restore files or directories from trash (defaults to original path).empty_trash: Permanently purge the trash folder (only after explicit user confirmation).gc_trash: Garbage-collect expired trash entries based on age threshold.mkdir: Create a new directory.touch: Create an empty file or update file timestamps.chmod: Change file/directory permissions with rollback and previous mode.chown: Change file/directory ownership with rollback and previous owner.stat: Get detailed file or directory metadata.disk_usage: Get disk usage statistics for a path.which: Find the path to an executable.cat: Read file content, optionally limited to a specific line range.glob: Find files matching glob patterns.grep: Search file contents using regex patterns.tree: Get a recursive directory tree as nested JSON.make_archive: Create archive files (zip, tar, etc.) with overwrite guards.unpack_archive: Unpack archive files safely with zip-slip protection.get_archive_formats: List supported archive formats.
Installation
Using Poetry (Recommended)
# Clone the repository
git clone <repository-url>
cd shutil-mcp
# Install dependencies
poetry install
# Optional: Install with performance enhancements (uvloop / winloop)
poetry install --all-extras
Using pip
# Install from PyPI
pip install shutil-mcp
# Or install in editable mode with speed dependencies
pip install -e ".[speed]"
Usage
Standard Input/Output (stdio) - Default Mode
shutil-mcp --transport stdio
With jail restriction:
shutil-mcp --transport stdio --jail /path/to/projects
HTTP Transports (SSE and/or Streamable HTTP)
For web-based MCP clients (such as llama.cpp WebUI), you can run with HTTP transport:
# SSE only (compatible with llama.cpp WebUI)
shutil-mcp --transport sse --jail /path/to/projects --port 8000
# Streamable HTTP only
shutil-mcp --transport streamable-http --jail /path/to/projects --port 8000
# Both SSE and Streamable HTTP on the same server
shutil-mcp --transport sse streamable-http --jail /path/to/projects --port 8000
Endpoints:
- SSE:
http://localhost:8000/sse - Streamable HTTP:
http://localhost:8000/mcp
Options:
--transport: Transport protocol(s) (stdio,sse,streamable-http, default:stdio)--port: Port to listen on (default: 8000)--host: Host to bind to (default: 0.0.0.0)--jail: Required for HTTP transports. Restrict file system operations to this directory tree for security.--api-key: Optional. Enable mandatory API key authentication (X-API-KeyorAPI-Keyheader).
Development
See DEVELOPMENT.md for detailed development instructions.
Running Tests
poetry run pytest -n auto
Code Quality
# Run linting and auto-fix issues
./scripts/lint-check-and-fix.sh
# Run static type checking (strict mode)
./scripts/type-check.sh
# Run code formatter and trailing whitespace cleanup (cross-platform Linux & macOS)
./scripts/code-format.sh
License
MIT
shutil MCP questions
What tools does shutil MCP provide?
It exposes 17 tools, including restore, empty_trash, gc_trash, mkdir, touch.
How does the server handle file deletions?
The server uses a soft-delete mechanism where files are moved to a .trash directory instead of being permanently deleted immediately.
Does it support web-based MCP clients?
Yes, it includes built-in support for SSE and Streamable HTTP transports, making it compatible with clients like llama.cpp WebUI.
How are file operations made safe for AI agents?
The server returns structured JSON instead of raw text and includes tool annotations like readOnlyHint and destructiveHint to help agents understand risks.