What can you do with this server?

The mcp-macclean server allows you to discover, preview, and safely delete caches from multiple package managers (Maven, pnpm, npm, yarn, pip, uv, go) and macOS system caches. * list_caches: Scans and reports the locations and disk usage of the specified caches. You can filter by specific targets or provide custom paths. * plan_cleanup: Generates a detailed cleanup plan (with options like pnpm force store, Go mod/build cache toggles, and Maven retain_latest) showing what would be deleted and how much space reclaimed, without actually removing anything. * execute_cleanup: Performs the actual deletion only when confirm=true and the environment variable MACCLEAN_ALLOW_EXECUTE=true are set. Returns real deletion stats: file count and reclaimed space per target. Safety features: By default, the server works in read-only preview mode; actual cleanup requires explicit two‑level opt‑in. Output is capped to the top 25 largest candidates to avoid overwhelming reports, and each package manager uses a tailored cleanup strategy (e.g., Maven keeps only the latest version per artifact, pnpm is conservative). Targets and cache paths are fully configurable, and a CLI is available that mirrors the server's functionality with the same safety gates.

Which integrations are available for this server?

Allows cleaning of npm cache (e.g., ~/.npm/_cacache) by discovering, previewing, and optionally deleting cache files. Allows cleaning of pnpm store cache (with force_store mode for deletion) and provides cache reporting. Allows cleaning of yarn cache directory by discovering, previewing, and optionally deleting cache files.

How do I use mcp-macclean?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-macclean preview my npm and pip caches" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-macclean

by caozhaoliang

Overview Schema Source Related Servers Score Discussions Admin

Python

Local

mcp-macclean

本机多包管理器缓存清理 MCP 服务。

支持统一发现、预览并（经确认后）清理：

maven
pnpm
npm
yarn
pip
uv
go
macos_caches

默认安全策略：只预览，不删除。真正删除需要同时满足：

调用 execute_cleanup 时 confirm=true
.env 中 MACCLEAN_ALLOW_EXECUTE=true

安装

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Related MCP server: Local AI MCP

配置

cp .env.example .env

按需编辑 .env。关键项：

配置	含义	默认
`MACCLEAN_ALLOW_EXECUTE`	是否允许真实删除	`false`
`MACCLEAN_DEFAULT_TARGETS`	默认 targets	全部
`MACCLEAN_MAX_CANDIDATES`	plan/execute 明细最多返回条数（按体积 Top-N）	`25`
`MACCLEAN_MAVEN_PATH`	Maven 本地仓库父目录（含 `repository`）	`~/.m2`
`MACCLEAN_NPM_CACHE`	npm cache 根目录	`~/.npm`
`MACCLEAN_YARN_CACHE`	yarn cache，空则自动探测	空
`MACCLEAN_PNPM_STORE`	pnpm store，空则自动探测	空
`MACCLEAN_PIP_CACHE`	pip cache，空则自动探测	空
`MACCLEAN_UV_CACHE`	uv cache，空则自动探测	空
`MACCLEAN_GO_MODCACHE`	Go module cache	空
`MACCLEAN_GO_BUILDCACHE`	Go build cache	空
`MACCLEAN_GO_CLEAN_MOD`	默认是否清理 Go mod	`false`
`MACCLEAN_GO_CLEAN_BUILD`	默认是否清理 Go build	`true`
`MACCLEAN_MACOS_CACHES_PATH`	`~/Library/Caches` 扫描根	`~/Library/Caches`
`MACCLEAN_MACOS_CACHES_COMMAND_TIMEOUT`	官方命令超时（秒）	`300`

更完整注释见 .env.example。

MCP 注册示例

Claude Code / MCP client 配置示例：

{
  "mcpServers": {
    "macclean": {
      "command": "/绝对路径/mcp-macclean/.venv/bin/python",
      "args": ["-m", "macclean.server"],
      "cwd": "/绝对路径/mcp-macclean"
    }
  }
}

注意：

必须使用虚拟环境里的 Python（或已 pip install -e . 的解释器），不要写裸的 python。在本机若 python 指向 pyenv 的 2.7，会立刻 No module named macclean，MCP 表现为 Connection closed。
command 与 cwd 请写绝对路径；~ 在部分 MCP 客户端中不会展开。

也可使用 venv 入口脚本启动 MCP：

.venv/bin/macclean-mcp
# 或
.venv/bin/python -m macclean.server

命令行入口（非 MCP）

安装后可用 CLI 直接 list / plan / execute，逻辑与 MCP 工具一致，门禁相同。

# 可编辑安装后
.venv/bin/macclean list
.venv/bin/macclean plan --targets maven,macos_caches
.venv/bin/macclean execute --targets macos_caches --confirm

# 未安装入口时
.venv/bin/python -m macclean list --json

常用参数：

参数	说明
`--targets a,b`	逗号分隔 targets；省略则用配置默认
`--path PATH`	仅单 target 时覆盖缓存路径
`--json`	JSON 输出
`--env-file PATH`	指定 `.env`
`--confirm`	`execute` 必填
`--mode force_store`	pnpm 强制清 store
`--go-mod` / `--no-go-mod`	Go module cache
`--go-build` / `--no-go-build`	Go build cache

示例：

.venv/bin/macclean list --targets macos_caches
.venv/bin/macclean plan --targets macos_caches --json
# 确认 .env 中 MACCLEAN_ALLOW_EXECUTE=true 后再执行
.venv/bin/macclean execute --targets macos_caches --confirm

工具说明

`list_caches`

发现缓存位置与占用。

参数：

targets：可选，如 ["maven","uv"]
path：可选，仅单 target 时作为自定义路径

`plan_cleanup`

生成删除计划，不会删除任何文件。

参数：

targets
path
options：
- mode: default | force_store（pnpm）
- go_mod / go_build
- retain_latest（maven）

候选 path 为相对该 target 缓存根的路径，便于浏览与筛选，例如 Maven：

缓存根：~/.m2/repository
候选：com/example/demo/1.0.0-SNAPSHOT

输出限制：

size_bytes=0 的候选不展示
明细列表默认只返回体积最大的 25 条（MACCLEAN_MAX_CANDIDATES）
candidate_count / reclaimable_* 仍是全量统计；被截断时 message 会注明 showing top N of M

`execute_cleanup`

执行清理。

参数：

confirm：必须为 true
targets / path / options

若 MACCLEAN_ALLOW_EXECUTE=false 或未确认，将拒绝执行。

成功执行后会返回真实删除统计（删除前实测，非 plan 预估）：

字段	含义
`total_deleted_count`	删除的候选根目录/条目数
`total_deleted_file_count`	真实删除的文件数
`total_reclaimed_bytes` / `total_reclaimed_human`	真实回收体积
`results[].deleted`	每项：`path`、`file_count`、`size_bytes`、`size_human`（按体积 Top-N，默认 25）
`results[].deleted_file_count`	该 target 真实删除文件数

说明：deleted 明细可能被截断，但 deleted_count / reclaimed_* / 响应级 total 字段始终是全量真实删除统计。

各 target 策略摘要

target	默认策略
maven	每个 `groupId:artifactId` 仅保留最新版本目录
npm	清理 `~/.npm/_cacache` 内容
yarn	清理 yarn cache 内容
pnpm	默认只报告；`mode=force_store` 才清理 store 内容
pip	清理 pip cache 内容
uv	清理 uv cache 内容
go	默认清理 build cache；mod 需显式开启
macos_caches	规则识别 `~/Library/Caches` 开发工具项；Homebrew 走 `brew cleanup`，其它白名单目录 `delete_children`；未知不删

开发

source .venv/bin/activate
pytest -v

安全提示

先 plan_cleanup，确认候选后再执行。
生产/共享机器上保持 MACCLEAN_ALLOW_EXECUTE=false，仅在明确需要时打开。
Maven 清理按版本新旧，不分析项目是否仍引用旧版本。
pnpm 默认保守，避免误删导致大规模重下。

Available Tools

3 tools

execute_cleanupB

执行缓存清理。必须 confirm=true，且 .env 中 MACCLEAN_ALLOW_EXECUTE=true。

ParametersJSON Schema

Name	Required	Description	Default
`path`	No
`confirm`	No
`options`	No
`targets`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description does not disclose behavioral traits such as destructiveness, side effects, or what happens to caches. With no annotations provided, this is a significant gap for a cleanup tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short and to the point, but it lacks structure and front-loading of key information beyond the prerequisites.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 4 parameters, no schema descriptions, and an output schema present, the description fails to provide adequate context on parameter meanings, return values, or behavioral implications.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description only adds the condition for confirm. It does not explain path, options, or targets, leaving the agent without sufficient parameter guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool executes cache cleanup and specifies the required conditions (confirm=true and env var). This distinguishes it from siblings list_caches (list) and plan_cleanup (plan).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states that confirm must be true and the env var MACCLEAN_ALLOW_EXECUTE must be set, which guides when to use the tool. However, it does not mention when not to use it or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_cachesB

发现本机包管理器缓存位置与占用。

ParametersJSON Schema

Name	Required	Description	Default
`path`	No
`targets`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states the tool discovers cache locations and usage, implying a read-only operation, but does not explicitly confirm non-destructiveness, permissions, or scope (e.g., whether it scans all or specific package managers).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that conveys the core purpose concisely. However, it lacks detail on parameters and behavior, so it is not optimally informative for the size.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has two optional parameters and an output schema, the description omits guidance on parameter usage and filtering capabilities. The output is covered by the schema, but the description fails to mention that it can target specific package managers or a custom path, making it incomplete for informed usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the two optional parameters ('path' and 'targets'). The enum for 'targets' gives some hint, but no textual meaning is provided, leaving agents to guess the purpose and valid usage of these parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool discovers local package manager cache locations and disk usage, which matches the 'list' name. It distinguishes from siblings 'plan_cleanup' and 'execute_cleanup' by focusing on inspection rather than planning or execution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives. However, the sibling names ('plan_cleanup', 'execute_cleanup') imply it is a precursor for cleanup tasks, giving indirect context. A clear when-to-use statement is missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

plan_cleanupB

生成缓存清理计划（不会删除任何文件）。

ParametersJSON Schema

Name	Required	Description	Default
`path`	No
`options`	No
`targets`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description partially addresses behavior by stating the tool is non-destructive. However, it omits details on failure modes, side effects of options, or output format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that is front-loaded. However, it sacrifices completeness for brevity, missing parameter and usage details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and three undocumented parameters, the description is insufficient. It does not explain what the plan looks like or how to configure the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description adds no information about the three parameters (path, options, targets). This leaves the agent without guidance on how to fill these fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action (generate a cache cleanup plan) and explicitly notes it does not delete files. This distinguishes it from sibling tools 'list_caches' and 'execute_cleanup'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for planning rather than execution (by stating it won't delete files), but it does not provide explicit guidance on when to use this tool over siblings or any context for prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

3 tool updatesv0.1.0Jul 29, 2026
- First observedexecute_cleanup
- First observedlist_caches
- First observedplan_cleanup

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0

Disambiguation5/5

Each tool has a clear, distinct purpose: listing caches, planning cleanup (dry-run), and executing cleanup. No ambiguity.

Naming Consistency5/5

All tools use consistent snake_case verb_noun pattern: list_caches, plan_cleanup, execute_cleanup.

Tool Count5/5

Three tools is appropriate for a focused cleanup utility—covers all necessary steps without unnecessary bloat.

Completeness5/5

Covers the full cleanup workflow: discovery (list), planning (plan), and execution (execute). No obvious gaps.

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

mcpcheck B
io.github.joeyough
Scan any MCP server for tool-poisoning, security, auth & license. Trust score before install.
Penetration Testing Security
21
mcpOAuth
io.artifacta
Artifact store for AI agents. Hosted OAuth at mcp.artifacta.io/mcp; local stdio via npm/PyPI.
File Systems Cloud Storage Developer Tools
21
strata
ai.klavis
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Agent Orchestration Autonomous Agents Developer Tools
25,748
MCP FortressOAuth
io.github.mcp-fortress
Security scanner for MCP servers. Detect vulnerabilities, prompt injection, and tool poisoning.
Security Testing & QA Tools Penetration Testing
2

Related MCP Servers

ACE-MCP
Code Analysis Search RAG Systems
0215AndrewFeng
A
license
Not graded
quality
B
maintenance
Enables AI clients to perform local code search, indexing, and analysis across Java, JavaScript/TypeScript, .NET/C#, and Python projects through the MCP protocol.
Updated 12 days ago (2026-08-28 03:01 UTC)
1
Apache 2.0
Local AI MCPofficial
AI & Machine Learning Developer Tools
TMHSDigital
A
license
A
quality
A
maintenance
Unified MCP server for managing local model runtimes (Ollama, LM Studio, etc.), enabling provider-agnostic discovery, lifecycle management, hardware-fit checks, and delegated inference.
Updated 9 days ago (2026-08-31 06:22 UTC)
16
40
Creative Commons Attribution Non Commercial No Derivatives 4.0 International
FilePilot AI
File Systems Search Text Summarization
cuiheng511
A
license
Not graded
quality
B
maintenance
Local-first MCP server for safely searching, reading, summarizing, tagging, deduplicating, and organizing local files with scoped access, read-only defaults, and dry-run plans.
Updated a month ago (2026-07-27 01:07 UTC)
16
MIT
AI Knowledge Center MCP
Developer Tools Knowledge & Memory Command Line
AHappyAtlas
A
license
Not graded
quality
A
maintenance
Local-first MCP server that provides project context, verification gates, and structured tools for coding agents to discover knowledge, run diagnostics, and execute allowlisted commands within a repository.
Updated 2 months ago (2026-07-14 16:22 UTC)
35
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/caozhaoliang/mcp-macclean'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

mcp-macclean

安装

配置

MCP 注册示例

命令行入口（非 MCP）

工具说明

list_caches

plan_cleanup

execute_cleanup

各 target 策略摘要

开发

安全提示

Available Tools

Output Schema

TDQS

Output Schema

TDQS

Output Schema

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

ACE-MCP

Local AI MCPofficial

FilePilot AI

AI Knowledge Center MCP

Latest Blog Posts

MCP directory API

`list_caches`

`plan_cleanup`

`execute_cleanup`