PruneoPruneo MCP server: clean your Mac from Claude Code or Codex
Pruneo ships an MCP (Model Context Protocol) server in the same program. You connect it with one command, and your AI agent can see how much each section takes, list what can be cleaned, move what's safe to quarantine and restore it. What needs confirmation, what's protected and the Trash are up to you, in the app.
If you already work with an AI agent in the terminal, you don’t need to open another app to free up space. Ask it “what’s taking up space on my Mac?” or “clean the Node caches that can be deleted”, and the agent uses Pruneo to do it, with the same safety rules as the app.
What the Pruneo MCP server is
pruneo mcp is an MCP server that comes inside Pruneo: there’s nothing else to install. It speaks over stdio (JSON-RPC 2.0), runs on your Mac and doesn’t use the network.
The five tools
| Tool | What it does |
|---|---|
get_disk_overview |
Disk space and, per section, how much is safe, how much needs review, how much is protected and how much the agent can clean |
list_section_items |
What’s in a section: name, path with ~, size, risk and whether the agent can clean it |
get_quarantine |
What’s in quarantine: each batch, its size, its paths and when it expires |
clean_safe_items |
Moves what’s safe in a section to quarantine. paths picks what, dry_run simulates. Returns what it moved, how much it freed and how to undo it |
restore_from_quarantine |
Puts a batch back where it was |
How to connect it
With Pruneo installed in Applications:
pruneo mcp --install claudeThat adds Pruneo to Claude Code for all your projects. For Codex:
pruneo mcp --install codexWithout arguments, pruneo mcp --install shows how to connect it in Claude Code, Codex, Claude Desktop, Cursor and others. For any client that reads a JSON config:
{
"mcpServers": {
"pruneo": {
"command": "/Applications/Pruneo.app/Contents/Helpers/pruneo",
"args": ["mcp"]
}
}
}If you don’t have the pruneo command in your terminal yet, install it from the app, in Scheduled › “From the terminal” › “Install command”. Or use the full path: /Applications/Pruneo.app/Contents/Helpers/pruneo mcp --install claude.
What the agent can and can’t do
The agent can look at everything and clean only what’s safe: what shows up green in the app and is included in “Clean the safe stuff”. Always to quarantine, never deleted outright.
It refuses, even if you ask:
- What needs confirmation (yellow) and what’s protected (lock).
- The Trash and local Time Machine snapshots.
- Unknown folders identified by an AI agent.
- What gets cleaned with an official command that can’t be undone, like
docker system prune.
You decide those in the app, looking at each item.
Things to ask your agent
- “How much space can I free on my Mac without risk?”
- “Show me what the Node section takes up and clean only what’s safe.”
- “Simulate an Xcode cleanup and tell me how much it would free.”
- “Restore the last thing you cleaned.”
FAQ
What is MCP?
MCP (Model Context Protocol) is an open standard that lets AI agents use external tools. Claude Code, Codex, Claude Desktop and Cursor, among others, support it.
How do I connect Pruneo to Claude Code?
With Pruneo in Applications, run pruneo mcp --install claude in the terminal. Pruneo adds the server to Claude Code for you. For Codex, pruneo mcp --install codex.
Can the agent delete files?
It deletes nothing: it only moves what Pruneo marks as safe (green) to quarantine. What needs confirmation, what's protected, the Trash, Time Machine and unknown folders are rejected.
Can I undo what the agent did?
Yes. Every cleanup returns the quarantine batch and how to restore it. The agent can restore it with restore_from_quarantine, and you can do it from the app or with pruneo quarantine restore.
Does the MCP server connect to the internet?
No. It runs on your Mac, over stdio, and sends us nothing. What the agent reads from the scan (paths and sizes) reaches that agent's provider, under its terms.