shutil-mcp

一个使用 aioshutil 提供异步 shell 工具的 MCP 服务器。

该项目为 AI 代理提供了一组文件系统工具，返回结构化 JSON 输出而非原始文本。这使得 AI 模型能够更精确、更直接地使用文件系统数据。

功能特性

• 异步操作：利用 aioshutil 和线程执行器实现非阻塞文件系统任务。

• JSON 输出：所有工具返回压缩后的 JSON，针对 AI 代理进行了优化。

• Jail 支持：将文件系统访问限制在特定目录树内以增强安全性。

• 验证与完整性：mv 和 cp 在取消链接或完成操作前验证目标数据，防止部分失败时造成数据丢失。

• 可逆变更与撤销：chmod 和 chown 返回先前的模式和所有权，便于立即撤销/重做，并在失败时自动回滚。

• 软删除与恢复：rm 支持 trash=True 软删除，并配有对应的 restore 工具。

• Zip-Slip 防护：unpack_archive 验证所有归档成员路径，防止目录遍历 / zip-slip 攻击。

• 详细元数据：ls 和 stat 等工具提供全面的信息（大小、mtime、模式、所有者等）。

• HTTP 传输支持：内置对 SSE 和 Streamable HTTP 传输的支持。

Related MCP server: File Manager MCP Server

可用工具

• ls：列出目录内容及详细元数据。

• cp：递归复制文件或目录并进行验证。

• mv：移动/重命名文件或目录，并在删除前进行安全验证。

• rm：删除文件或目录（支持 trash=True 软删除）。

• restore：从回收站恢复文件或目录。

• chmod：更改文件/目录权限，支持回滚并返回先前模式。

• chown：更改文件/目录所有权，支持回滚并返回先前所有者。

• disk_usage：获取路径的磁盘使用统计信息。

• which：查找可执行文件的路径。

• cat：读取文件内容，可选择限制在特定行范围内。

• glob：查找匹配 glob 模式的文件。

• grep：使用正则表达式搜索文件内容。

• tree：以嵌套 JSON 形式获取递归目录树。

• make_archive：创建归档文件（zip、tar 等），带覆盖保护。

• unpack_archive：安全解压归档文件，带 zip-slip 防护。

• get_archive_formats：列出支持的归档格式。

安装

pip install shutil-mcp

使用方法

使用 stdio 传输运行

shutil-mcp --transport stdio

使用 jail 限制运行

shutil-mcp --transport stdio --jail /path/to/projects

作为 SSE 服务器运行

shutil-mcp --transport sse --jail /path/to/projects --port 8000

开发

详细开发说明请参阅 DEVELOPMENT.md。

许可证

MIT