Skip to main content
Glama

tidy-mcp

Your Downloads folder, cleaned by a local AI. Private. Undoable.

Point tidy at a messy folder. A local model looks at every file, gives it a real name and sorts it into folders. Nothing leaves your machine, and every run can be undone.

🚧 Early release. Feedback welcome.

tidy planning, applying and undoing a messy Downloads folder

IMG_2931.png            β†’  Receipts/2026-06-12_Amazon_receipt.png
Screenshot 11.04.12.png β†’  Screenshots/Code/python_KeyError_traceback.png
final_v3_real.pdf       β†’  Documents/Housing/Lease_Agreement_Bangalore_2025.pdf
IMG_2931 (1).png        β†’  _tidy_trash/   (duplicate)
Docker.dmg              β†’  _tidy_trash/   (installer older than 30 days)

How it works

scan β†’ plan (dry run) β†’ preview β†’ apply β†’ undo
  • Runs on Ollama, fully offline

  • Never deletes anything. Duplicates and old installers go to _tidy_trash/

  • Every applied plan can be undone

  • Only touches the top level of the folder you give it. Hidden files and symlinks are skipped

  • Works as a CLI (tidy) and as an MCP server for Claude, Cursor and other clients

Related MCP server: Smart File Organizer MCP Server

Setup

  1. Install Ollama and pull the models:

    ollama pull qwen2.5:7b
    ollama pull qwen2.5vl:7b
  2. Install tidy (needs Python 3.12+):

    uv tool install git+https://github.com/Tarunvaka/tidy-mcp

CLI

tidy plan ~/Downloads      # dry run: shows every change, moves nothing
tidy apply last            # asks before moving (or pass a plan ID)
tidy undo last             # puts everything back
tidy dupes ~/Downloads     # list duplicate files

MCP server

Add tidy to your MCP client. For Claude Desktop, edit claude_desktop_config.json:

{
  "mcpServers": {
    "tidy": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Tarunvaka/tidy-mcp", "tidy-mcp"]
    }
  }
}

For Claude Code:

claude mcp add tidy -- uvx --from git+https://github.com/Tarunvaka/tidy-mcp tidy-mcp

For Cursor, add the same command and args under mcpServers in ~/.cursor/mcp.json.

Then ask: "Tidy my Downloads folder." The assistant shows the plan and only applies it after you agree.

Tool

What it does

scan_folder

List the files tidy would look at

describe_file

Suggested name and folder for one file

plan_tidy

Build a dry-run plan

apply_plan

Apply an approved plan

undo

Reverse an applied plan

find_duplicates

Groups of identical files

Configuration

Optional. Create ~/.tidy/config.toml:

text_model = "qwen2.5:7b"
vision_model = "qwen2.5vl:7b"
limit = 500                      # max files per run
ignore = ["*.part", "keep-*"]    # file name patterns to leave alone

[[rules]]                        # send matching files to a fixed folder
match = "invoice"
folder = "~/Finance/Invoices"

workers (default 4) sets how many files are described at once. Answers are cached, so re-running on the same files is instant.

Any setting can also come from an environment variable such as TIDY_TEXT_MODEL. Plans and undo logs live in ~/.tidy (or $TIDY_HOME).

Development

uv sync
uv run python scripts/make_fixtures.py   # builds a fake messy folder
uv run pytest                            # includes property-based safety tests
uv run python scripts/eval_quality.py    # scores naming on 30 varied files (needs Ollama)

Current score with qwen2.5:7b + qwen2.5vl:7b: 29/30 folders correct, 30/30 names contain the key words.

Contributing

Issues labeled good first issue are a good place to start. See CONTRIBUTING.md.

Releasing

  1. Move the Unreleased notes in CHANGELOG.md under a new version heading.

  2. uv version --bump minor (or patch / major) and commit.

  3. git tag v$(uv version --short) && git push --tags

The Release workflow tests, builds, publishes to PyPI and creates the GitHub release.

License

MIT

Available Tools

6 tools
apply_planA

Apply a plan the user has approved. Files are moved, never deleted.

Inputs: plan_id (required). Returns: moves

describe_fileB
Read-only

Ask the local model for a better name and folder for one file.

Inputs: path (required). Returns: What the local model says about a file. Also the Ollama structured-output schem…

find_duplicatesC
Read-only

Groups of identical files. The first in each group is the original and is kept.

Inputs: path (required). Returns: groups

plan_tidyB

Build a dry-run plan for a folder. Nothing is moved. Show the plan to the user.

Inputs: path (required), limit. Returns: A dry-run plan for one folder. Nothing changes until it is applied.

scan_folderB
Read-only

List the files tidy would look at in a folder (top level only, no hidden files).

Inputs: path (required), limit. Returns: files

undoA

Put every file from an applied plan back where it was.

Inputs: plan_id (required). Returns: moves

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool maps to a distinct step in the tidy workflow (scan, plan, apply, undo) plus two focused helpers (find_duplicates, describe_file). The only mild overlap is scan_folder vs plan_tidy, since both inspect a folder, but descriptions make clear one lists and the other builds a dry-run plan.

    Naming Consistency4/5

    Nearly all tools follow a verb_noun pattern (scan_folder, plan_tidy, apply_plan, find_duplicates, describe_file). The bare 'undo' deviates slightly, but it's a universally understood single-action name and remains readable.

    Tool Count5/5

    Six tools is well within the sweet spot and every tool earns its place in the workflow. Nothing feels redundant or missing from the count perspective.

    Completeness4/5

    The surface covers the full lifecycle: scan, dry-run plan, apply, undo, plus duplicate detection and per-file LLM suggestions. Minor gaps exist, such as no way to selectively edit or exclude items in a plan, no history of past plans, and no explicit action to actually relocate detected duplicates.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables AI assistants to analyze, rename, categorize, and organize local documents using OCR, metadata extraction, and batch processing, with preview mode and undo support.
      13
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Official server for the ShieldFive end-to-end encrypted vault. Moves files off your computer into the vault, reading each copy back and verifying it before the original goes to a local trash folder (nothing deleted). Also finds duplicates by content and tidies folders. Decrypts on your machine; access is scoped, expiring, revocable and undoable.
      80 npm
      MIT
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables personal AI agents to triage digital clutter by classifying orphaned downloads, duplicate screenshots, and stale browser bookmarks, returning a prioritized decluttering queue with actionable recommendations. It runs locally as a zero-dependency Python MCP server that plugs into Claude Desktop, Cursor, or Windsurf.
      -