unclutr files MCP support: local duplicate scanning for AI workflows

This post is for technical users who want to connect unclutr files to AI tools through MCP (Model Context Protocol) for local duplicate-scan workflows. If you just want to clean duplicates manually in the app, you can ignore this entirely.

The goal of MCP support is simple: let an AI client ask unclutr files to run a local, read-only duplicate scan on paths you choose, then return structured results for analysis, triage, or follow-up workflows.

What MCP support currently provides

The `unclutr-files` MCP server runs locally over stdio. It is not a cloud service, and it does not expose delete/trash operations.

• Local server binary (`unclutr-mcp-server`) for MCP clients.
• Read-only tools for safe first-pass analysis.
• In-app onboarding in Settings → AI tools (MCP) for install/repair, self-test, and copying a Codex config snippet (direct builds).

Current tools (technical)

At the time of writing, the MCP server exposes two tools:

• scan_exact_duplicates — scans provided absolute paths and returns duplicate groups (exact matches only).
• resolve_common_paths — resolves natural-language path terms like Downloads, Desktop, or my external drives into usable paths.

This is intentionally narrow. The first MCP release is built for safe scanning and orchestration, not destructive actions.

Client setup examples (Codex, Claude Code, Cursor)

Use the exact command path shown by unclutr files → Settings → AI tools (MCP). The app can copy a Codex snippet directly, which is the safest option because it matches your installed setup.

In the examples below, replace <UNCLUTR_MCP_COMMAND_PATH> with the command path shown in the app.

OpenAI Codex (config.toml)

This is the snippet shape generated by the app for Codex:

[mcp_servers.unclutr-files]
command = "<UNCLUTR_MCP_COMMAND_PATH>"
cwd = "/"
enabled = true

Then restart Codex and start a new session so it reloads MCP servers.

Claude Code (CLI setup)

Claude Code supports adding a local stdio MCP server from the CLI. A practical setup command is:

claude mcp add unclutr-files --scope user -- "<UNCLUTR_MCP_COMMAND_PATH>"

Then verify with:

claude mcp list
claude mcp get unclutr-files

If you prefer JSON-based setup, Claude Code also supports adding MCP servers from JSON with claude mcp add-json.

Cursor (.cursor/mcp.json or ~/.cursor/mcp.json)

Cursor uses an mcp.json file for custom MCP servers. Add an entry like this (preserve existing servers):

{
  "mcpServers": {
    "unclutr-files": {
      "command": "<UNCLUTR_MCP_COMMAND_PATH>",
      "args": []
    }
  }
}

You can put this in a project config (.cursor/mcp.json) or global config (~/.cursor/mcp.json), then restart Cursor.

Why this is useful (real use cases)

1. Agent-assisted preflight before manual cleanup

Ask an AI client to scan selected paths and summarize where the biggest duplicate groups are, how much space is reclaimable, and which locations are likely cache-heavy. Then you still do the final review/delete in the app.

2. Faster path targeting for non-technical users

resolve_common_paths lets an agent translate natural requests like “scan my external drives and Downloads” into a concrete path list before running the duplicate scan.

3. Repeatable local audits

Technical users can build repeatable local workflows around the MCP server to compare scan outputs across known folders, NAS mounts, or project archives without giving an AI client broad filesystem access by default.

4. Safer AI integration than direct file operations

Because the MCP server currently exposes read-only scanning, it is a good fit for “analyze first, decide later” workflows. This aligns with the same design principle as unclutr files itself: review before removal.

Channel support: App Store vs direct download

The codebase supports two macOS distribution channels with different MCP behavior:

• Direct-download channel: MCP tooling enabled.
• App Store channel: MCP tooling disabled (MCP binaries are not bundled).

This split keeps the product clear and predictable across distribution channels while allowing advanced local tooling in direct builds.

Safety boundaries (what MCP does and does not do)

• Does: local duplicate scans on paths you explicitly pass to the tool call.
• Does: return structured scan results for analysis.
• Does not: expose delete/trash operations in the current implementation.
• Does not: automatically use app sandbox bookmarks yet (current server notes this explicitly).

That last point matters: MCP support is useful today, but it is still intentionally conservative.

Real example (video demo placeholder)

This section is where a short demo is most useful: show a real MCP client resolving paths, running a duplicate scan, and summarizing the results before switching to unclutr files for review.

Suggested demo script (short)

1. Open your MCP client and call resolve_common_paths with terms like Downloads and my external drives.
2. Run scan_exact_duplicates on the resolved paths.
3. Ask the client to summarize top duplicate groups by reclaimable size.
4. Switch to unclutr files and review/delete manually in the UI.

Who this is for (and who it is not for)

This is for users who want to build technical local workflows around duplicate scanning, automation, or AI-assisted triage.

If you only want a standard GUI cleanup flow, the core unclutr files app already covers that well without MCP.

What is next

The current MCP support is intentionally narrow and safety-first. The right next steps are not “more power” by default, but better clarity, stronger integration, and carefully designed tooling boundaries.