tidy
This MCP server lets you organize a folder with a local AI: scan, describe, dry-run plan, apply approved moves, undo, and find duplicates.
scan_folder: list top-level files tidy would inspect (hidden files skipped).describe_file: get a suggested name, category/folder, and short summary for one file from the local model.plan_tidy: build a dry-run plan of proposed moves/renames/trash without changing files.apply_plan: apply a user-approved plan; files are moved, never deleted.undo: reverse an applied plan and restore files to original locations.find_duplicates: group identical files, keeping the first as original.All processing is local/offline via Ollama, with moves kept undoable and duplicates/old installers sent to
_tidy_trash/.
Integrates with Ollama to run local text and vision models for analyzing files, suggesting names, and categorizing them into folders, all offline.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tidy clean up my Downloads folder β show me the plan before moving anything"
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.
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.

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 β undoRuns 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
Install Ollama and pull the models:
ollama pull qwen2.5:7b ollama pull qwen2.5vl:7bInstall 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 filesMCP 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-mcpFor 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 |
| List the files tidy would look at |
| Suggested name and folder for one file |
| Build a dry-run plan |
| Apply an approved plan |
| Reverse an applied plan |
| 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
Move the
Unreleasednotes inCHANGELOG.mdunder a new version heading.uv version --bump minor(orpatch/major) and commit.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 toolsapply_planA
Apply a plan the user has approved. Files are moved, never deleted.
Inputs: plan_id (required). Returns: moves
describe_fileBRead-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_duplicatesCRead-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_folderBRead-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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Your own computer's files from ChatGPT or Claude: folder rules, confirmations and undo.
Search photos and video moments by visual meaning, people, dates, and folders across local libraries, Apple Photos, and OneDrive. Manage collections, groups, favorites, people, and duplicate review. Synced metadata remains searchable while the desktop is offline; local and Apple Photos media access needs the owning device online with remote access enabled. OneDrive media can be accessed directly from the cloud. OAuth or Bearer API keys. Paid Cloud Access required; hosted visual search uses prepaid credits. Text-in-image search is semantic matching, not guaranteed exact OCR. Setup: https://organizewith.ai/en/guides/connect-ai-assistants
Read and search folders on your own computer with explicit consent. Files are never uploaded.
PDF and image tools for AI agents: compress, merge, split, OCR, sign. Runs locally, never uploads.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables AI assistants to analyze, rename, categorize, and organize local documents using OCR, metadata extraction, and batch processing, with preview mode and undo support.131MIT
- FlicenseNot gradedqualityDmaintenanceLets AI assistants analyze and organize local directories by file type, with dry-run support and safe sorting.-

@shieldfive/mcpofficial
AlicenseNot gradedqualityBmaintenanceOfficial 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 npmMIT- FlicenseNot gradedqualityNot gradedmaintenanceEnables 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.-