trash-cleaner-mcp-server

@dabing1022

About trash-cleaner-mcp-server

A desktop MCP service that scans for and removes junk files to keep your system clean and optimized.

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "trash-cleaner-mcp-server": {
      "command": "npx",
      "args": [
        "@childhoodandy/trash-cleaner-mcp-server"
      ]
    }
  }
}

Tools

获取当前操作系统的类型（例如：darwin, win32, linux）。

获取指定文件夹的大小（字节）。

在指定目录中查找符合条件的文件。

在指定目录中查找符合条件的文件和文件夹。

在指定目录中查找符合条件的文件夹。

分析目录中文件的类型分布、大小分布等信息。

计算文件的 MD5/SHA256 哈希值，用于文件完整性校验。

获取文件的MIME类型和基本信息。

删除指定文件或文件夹。默认永久删除，可通过 useTrash 选项移到系统垃圾桶。需用户确认。

检查指定的文件或目录路径是否存在。

清空操作系统垃圾桶。这是一个不可恢复的操作！请谨慎使用。

显示当前系统不是 macOS 的警告信息。

清理各种应用程序缓存文件，包括用户缓存目录、应用程序保存的状态等。仅适用于 macOS 系统。

清理系统临时文件目录中的临时文件。仅适用于 macOS 系统。

清理已卸载应用程序的配置文件、缓存和其他残留文件。仅适用于 macOS 系统。

智能清理系统垃圾文件，支持不同的清理级别。仅适用于 macOS 系统。

清理 VSCode 及相关编辑器的低版本扩展。

生成 VSCode 及相关编辑器低版本扩展的报告。

在指定目录中查找超过指定大小的大文件。

执行全盘扫描，识别文件分布和大小情况

扫描指定目录，分析文件分布和大小情况

扫描常见类型的垃圾文件 (缓存, 临时文件, 日志等)。依赖于 junk_rules.json 配置文件。

查看应用程序最近的运行日志（combined.log）。

清空应用程序的主运行日志文件（combined.log）。这是一个破坏性操作，请谨慎使用！

Overview

What is trash-cleaner-mcp-server?

trash-cleaner-mcp-server is a desktop MCP service that provides tools to scan, analyze, and clean junk files. It is primarily optimized for macOS, with cross-platform support (Windows, Linux) planned. The server is built with Bun.js and TypeScript and is intended for users who want to manage system clutter, application remnants, and temporary files programmatically via the Model Context Protocol.

How to use trash-cleaner-mcp-server?

The server can be run using bunx @childhoodandy/trash-cleaner-mcp-server or npx @childhoodandy/trash-cleaner-mcp-server. For development, clone the repository, run bun install, then bun start. Configuration for logging is in src/utils/logger.ts and scheduled task definitions are stored at ~/.trash-cleaner/schedules.json. The server registers numerous tools callable via MCP, with most cleaning tools marked as macOS-only.

Key features of trash-cleaner-mcp-server

Intelligent scanning of junk files (caches, logs, temp files)
Selective cleaning for application caches, temp files, and remnants
VS Code extension management (find and clean outdated extensions)
Filesystem utilities (directory analysis, file finding, size calculation, deletion)
System information detection (OS type)
Audit logging with view and clear tools
Scheduled task system with cron or interval-based execution

Use cases of trash-cleaner-mcp-server

Clean application caches and temporary files on macOS with dry-run support
Remove configuration and cache files left by uninstalled applications
Identify and delete outdated VS Code extensions across editors like VSCodium and Cursor
Find large files in a directory to free up disk space
Automate regular system cleaning tasks using the built-in scheduler

FAQ from trash-cleaner-mcp-server

Which operating systems are supported?

Most cleaning tools (cleanAppCaches, cleanTempFiles, cleanAppRemnants, smartCleanSystem) are designed and tested specifically for macOS. Cross-platform support for Windows and Linux is planned. The server can report the operating system via getSystemType.

How do I schedule cleaning tasks?

Use the TrashCleaner_Scheduler tools. You can create a task by specifying a name, a cron expression, and either an exact toolName or a fuzzy toolQuery (e.g., "clean app caches"). Tasks can be listed, updated, enabled, disabled, deleted, triggered manually, and their execution history can be viewed.

Where are logs and scheduled task definitions stored?

Audit logs are written to a combined.log file. The viewAuditLog tool reads from this file. Scheduled task definitions are stored in ~/.trash-cleaner/schedules.json.

How can I safely delete files?

Use the deletePath tool. It requires explicit confirmation (confirm: true) and an additional dangerConfirm flag for potentially risky deletions. Extra checks are in place to prevent accidental deletion of critical paths.

What options are available for cleaning tools?

Most cleaning tools accept a dryRun option (default true) to preview changes without deleting. Some support an olderThan parameter (in days). The smartCleanSystem tool has a cleanLevel enum with values "safe", "normal", and "deep".

Frequently asked questions

Which operating systems are supported?

Most cleaning tools (`cleanAppCaches`, `cleanTempFiles`, `cleanAppRemnants`, `smartCleanSystem`) are designed and tested specifically for macOS. Cross-platform support for Windows and Linux is planned. The server can report the operating system via `getSystemType`.

How do I schedule cleaning tasks?

Use the `TrashCleaner_Scheduler` tools. You can create a task by specifying a name, a cron expression, and either an exact `toolName` or a fuzzy `toolQuery` (e.g., "clean app caches"). Tasks can be listed, updated, enabled, disabled, deleted, triggered manually, and their execution history can be viewed.

Where are logs and scheduled task definitions stored?

Audit logs are written to a `combined.log` file. The `viewAuditLog` tool reads from this file. Scheduled task definitions are stored in `~/.trash-cleaner/schedules.json`.

How can I safely delete files?

Use the `deletePath` tool. It requires explicit confirmation (`confirm: true`) and an additional `dangerConfirm` flag for potentially risky deletions. Extra checks are in place to prevent accidental deletion of critical paths.

What options are available for cleaning tools?

Most cleaning tools accept a `dryRun` option (default `true`) to preview changes without deleting. Some support an `olderThan` parameter (in days). The `smartCleanSystem` tool has a `cleanLevel` enum with values "safe", "normal", and "deep".

Comments

Basic information

More Other MCP servers

ICSS

chokcoco

不止于 CSS

20.7K

MCP Toolbox for Databases

googleapis

MCP Toolbox for Databases is an open source MCP server for databases.

15.9K

YOUB

Connect your AI assistant to your own YOUB endurance training account. Read recorded activities with full analysis, planned sessions, race goals, wellness (HRV, sleep, resting HR) and your athletic profile. Create or mov

EverArt

modelcontextprotocol

Model Context Protocol Servers

88.1K

Sequential Thinking

modelcontextprotocol

Model Context Protocol Servers

88.2K

About trash-cleaner-mcp-server

Config

Tools

TrashCleaner_Os_GetSystemType

TrashCleaner_Fs_GetFolderSize

TrashCleaner_Fs_ListDirectory

TrashCleaner_Fs_FindFiles

TrashCleaner_Fs_FindPaths

TrashCleaner_Fs_FindDirectories

TrashCleaner_Fs_AnalyzeDirectory

TrashCleaner_Fs_GetFileHash

TrashCleaner_Fs_GetFileType

TrashCleaner_Fs_DeletePath

TrashCleaner_Fs_CheckPathExists

TrashCleaner_Fs_EmptyTrash

TrashCleaner_Cleaner_MacOSWarning

TrashCleaner_Cleaner_CleanAppCaches

TrashCleaner_Cleaner_CleanTempFiles

TrashCleaner_Cleaner_CleanAppRemnants

TrashCleaner_Cleaner_SmartCleanSystem

TrashCleaner_Cleaner_CleanVSCodeExtensions

TrashCleaner_Cleaner_ReportVSCodeExtensions

TrashCleaner_Cleaner_FindLargeFiles

TrashCleaner_Scan_ScanFullSystem

TrashCleaner_Scan_ScanDirectory

TrashCleaner_Scan_ScanJunkFiles

TrashCleaner_Audit_ViewAuditLog

TrashCleaner_Audit_ClearAuditLog

Overview

What is trash-cleaner-mcp-server?

How to use trash-cleaner-mcp-server?

Key features of trash-cleaner-mcp-server

Use cases of trash-cleaner-mcp-server

FAQ from trash-cleaner-mcp-server

Which operating systems are supported?

How do I schedule cleaning tasks?

Where are logs and scheduled task definitions stored?

How can I safely delete files?

What options are available for cleaning tools?

Frequently asked questions

Which operating systems are supported?

How do I schedule cleaning tasks?

Where are logs and scheduled task definitions stored?

How can I safely delete files?

What options are available for cleaning tools?

Comments

More Other MCP servers

ICSS

MCP Toolbox for Databases

YOUB

EverArt

Sequential Thinking