mac-doctor-mcp

让 AI 查看 Mac 的内存、存储和硬件状态，再由人决定是否清理。Python 3.12+，通过本地 stdio 提供 MCP 工具。无需常驻监控，也不会自动清理或结束进程。

图中内存来自本机只读采集；清理与回滚来自临时演示文件，路径已脱敏。

能做什么

• 内存：读取 memory_pressure -Q、vm_stat、sysctl vm.swapusage，显示物理内存、swap、风险等级，以及按 Claude Code、Codex、EGO、Hermes、Cursor 等应用归类的进程。检测 cwd 位于已删除 .worktrees/<name> 的进程，只提示，不杀进程。

• 存储：显示指定目录下最大的直接子项和卷剩余空间。安装了 Mole 且支持 JSON 分析时，额外调用 mo analyze --json <root> 返回候选，保留 scan_status。不完整扫描的大小只是下界；候选不等于可以删除。

• 硬件（可选）：安装了 siltop 时，读取 siltop report today --json 和 siltop --json 单次实时快照。未安装或命令失败会返回 available: false 和原因；部分成功的数据仍保留。不会安装 agent、启动服务或运行压力测试。

• 清理事务：生成清理计划、移入隔离区、回滚、中断恢复及到期清空。已在真机验证：单个缓存目录执行后回滚，文件数与整树内容 SHA 一致；一次 14 项、约 16.7 GiB 的包缓存和安装镜像清理已移入隔离区。

Linux 采集器仅供开发和测试，内存读取 /proc/meminfo，硬件显示不支持；本项目面向 macOS。

怎样理解内存

输出包含 total_bytes、available_bytes、swap_used_bytes、free_percent、risk。Mac 的 available_bytes 是 vm_stat 的 free pages × page size，不包含可回收缓存；free_percent 来自 macOS 的 memory pressure 指标，不能用前两个字段相除代替。Linux 的 available 则来自 MemAvailable，两平台口径不同。

Mac 风险阈值：free percent < 10，或 < 20 且 swap ≥ 4 GiB，标为 pressure；否则 free percent < 25、swap ≥ 1 GiB 或压缩内存 ≥ 物理内存 30% 时标为 watch；其余为 healthy。swap 可能来自历史压力，单次高 swap 不等于当前正在吃紧。进程 RSS 和分组 RSS 只适合相对比较，共享页会重复计数。

Related MCP server: DiskSweep MCP

本地运行

安装 uv 后直接启动（uv 可按需准备 Python 3.12+）：

uvx --from git+https://github.com/bmdy6/mac-doctor-mcp mac-doctor-mcp

服务使用标准输入输出，启动后等待 MCP 客户端连接。可选工具从服务的 PATH 查找；没有 siltop 或 Mole 也能使用内存与存储采集。GUI 客户端若找不到 uv，请把配置中的 command 换成 uv 可执行文件的绝对路径。

MCP 配置

无需克隆仓库。以下配置直接从 GitHub 安装运行。

Claude Code

在客户端的 .mcp.json 中配置：

{
  "mcpServers": {
    "mac-doctor": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/bmdy6/mac-doctor-mcp", "mac-doctor-mcp"]
    }
  }
}

也可使用 CLI 注册：

claude mcp add --transport stdio mac-doctor -- uvx --from git+https://github.com/bmdy6/mac-doctor-mcp mac-doctor-mcp

Codex

在 ~/.codex/config.toml 配置。建议先只启用三个 inspect 工具：

[mcp_servers.mac-doctor]
command = "uvx"
args = ["--from", "git+https://github.com/bmdy6/mac-doctor-mcp", "mac-doctor-mcp"]
enabled_tools = ["inspect_memory", "inspect_storage", "inspect_hardware"]
tool_timeout_sec = 180

配置格式参见 Claude Code 官方文档与 Codex 官方 MCP 文档。这些是配置示例，不会替你修改客户端配置。

工具列表

存储扫描可能较慢，建议先指定较小的目录，例如 {"roots":["/path/to/cache"],"top":5}。无权限、符号链接及含禁区内容的项目可能显示为 skipped。Mole 不支持 analyze --json 时跳过，不回退到交互界面或清理命令；Mole 的 HOME、缓存和临时目录隔离在一次性临时目录，避免影响其真实状态。

安全规则

1. 先计划再确认：AI 必须展示每项路径、原因、风险、总大小和确认码；用户亲自回传确认码后才能调用 apply_plan。确认码只校验匹配，服务器不能证明是谁输入的，仍需客户端审批约束。

2. 白名单与禁区：默认允许缓存、日志、Downloads 等根目录下的项目；项目根目录下只允许已知构建产物目录（如 node_modules、.next、DerivedData）。禁区优先，包含 .git、密钥目录、钥匙串、知识库、Hermes、Codex、Agent 技能与记忆目录等，详见 policy.py。自定义白名单也不能覆盖禁区。

3. 隔离不等于释放空间：apply 使用同卷 rename，不复制；真正释放空间需要到期 purge。跨卷目标拒绝执行，回滚遇到原位置冲突不会覆盖。

4. 中断恢复：journal 未恢复时拒绝新的执行，使用 recover 恢复；有审计日志。计划有有效期，执行时重新验证文件身份。现有核心不承诺逐文件内容 SHA 校验。

5. 永久清空单独确认：purge_quarantine 默认保留 7 天，最少 1 天；先调用无确认码预览，用户确认后才传码清空。

6. 本地权限边界：以当前用户权限运行，不使用 sudo。内存输出不包含完整 argv 或环境变量；存储和第三方硬件 JSON 可能含路径、用户名或应用信息，分享前先脱敏。

默认状态目录为 ~/.mac-doctor，可通过 MAC_DOCTOR_HOME 修改；配置文件为 ~/.config/mac-doctor/config.json，可通过 MAC_DOCTOR_CONFIG 修改。存储工具加载事务对象时会初始化状态目录，但不会修改扫描目标。

配置文件可按需设置以下字段（不配置则使用默认值）：

{
  "allow_roots": ["~/Library/Caches", "~/.cache"],
  "artifact_roots": ["~/Projects"]
}

与 Mole 的关系

这是独立的 MCP 服务，不是 Mole 官方项目。Mole 是可选的只读分析来源：只调用 mo analyze --help 检查能力，再调用 mo analyze --json <root>，从不调用 clean。清理方案、确认码、隔离和回滚由本项目实现。

工具注解是客户端提示，不是权限控制；plan_cleanup 的 readOnlyHint 指目标文件不变，仍会保存本地计划。确认码不证明用户身份，客户端必须审批写操作，不能让模型自行生成并回传确认码来代替用户同意。

开发与验收

uv run pytest -q
uv build --wheel
uv run python scripts/inspect_smoke.py --root ./src

测试用固定文本覆盖 Mac 解析与风险阈值，用 mock 覆盖可选工具缺失、失败及只读命令边界；事务测试只操作 pytest 临时目录。smoke 脚本通过真实 stdio MCP 连接，列出工具并只调用三个 inspect，将存储路径、worktree 名和硬件身份字段脱敏后输出摘要；服务状态隔离在临时目录。Mole 未安装时，smoke 只能验证跳过分支。