MCP Duplicate File Manager Server
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., "@MCP Duplicate File Manager Server find duplicate files in my Downloads folder"
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.
MCP Duplicate File Manager Server
A Model Context Protocol (MCP) server that enables LLM-based AI agents to manage duplicate files efficiently. Designed for seamless integration with LLMs and AI agents using the MCP protocol with intelligent duplicate detection and safe deletion capabilities.
Features
Exposes file management tools for LLM agents via MCP:
list_files: List files in directories with optional filteringfind_duplicates: Find duplicate files based on content hash (MD5)delete_duplicates: Safely delete duplicate files with intelligent copy detection
Smart copy detection: Prioritizes deleting files with copy indicators ("copy", "(1)", "(2)", etc.)
Content-based duplicate detection using MD5 hashing for accuracy
Recursive directory scanning with optional pattern matching
Dry-run mode for safe preview before actual deletion
Simple integration with Claude, MCP clients, or other LLM-based agents
Related MCP server: File Manager MCP
Quickstart
1. Install & Run
Run the MCP Duplicate File Manager Server using uvx:
uvx --from git+https://github.com/deerajd/DuplicateFileRemover-MCP.git mcp-server2. Integrate with Your LLM Agent
Add the following to your tool configuration (for Claude, MCP clients, etc.):
{
"mcpServers": {
"DuplicateListor": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/deerajd/DuplicateFileRemover-MCP.git",
"mcp-server"
]
}
}
}This configuration launches the MCP Duplicate File Manager Server as a subprocess, exposing file management tools to your LLM agent.
3. Usage
From your LLM agent, you can call:
List Files in Directory
list_files(directory="./Documents", pattern="*.pdf") # List PDF files
list_files(directory="/home/user", include_hidden=True) # Include hidden files
list_files() # List all files in current directoryFind Duplicate Files
find_duplicates(directory="./Downloads") # Find duplicates in Downloads
find_duplicates(directory="/Users/john/Desktop", recursive=False) # Non-recursive search
find_duplicates() # Find duplicates in current directoryDelete Duplicate Files
delete_duplicates(directory="./Documents", dry_run=True) # Preview what would be deleted
delete_duplicates(directory="./Documents", dry_run=False) # Actually delete duplicates
delete_duplicates(directory="./Pictures", recursive=True) # Recursive deletion with previewThe server provides detailed responses including:
List of files with metadata (name, size, type, path)
Duplicate file groups organized by content hash
Deletion results with preserved originals and deleted copies
Error handling for inaccessible files or directories
API Reference
list_files(directory=".", pattern="*", include_hidden=False)
Parameters:
directory(str): Directory path to list files from (default: current directory)pattern(str): File pattern to match (e.g., ".py", ".txt") (default: "*")include_hidden(bool): Whether to include hidden files (default: False)
Returns: List of dictionaries containing file information (name, size, type, path, modified)
find_duplicates(directory=".", recursive=True)
Parameters:
directory(str): Directory path to search for duplicates (default: current directory)recursive(bool): Whether to search recursively in subdirectories (default: True)
Returns: Dictionary with hash as key and list of duplicate file paths as values
delete_duplicates(directory=".", recursive=True, dry_run=True)
Parameters:
directory(str): Directory path to search for duplicates (default: current directory)recursive(bool): Whether to search recursively in subdirectories (default: True)dry_run(bool): If True, only show what would be deleted without actually deleting (default: True)
Returns: Dictionary with information about deleted files and preserved originals
Smart Copy Detection
The server intelligently identifies and prioritizes deletion of files with copy indicators:
copy- Files containing "copy" in the filename(1),(2), etc. - Files with numbered suffixes_copy,-copy- Files with copy prefixes/suffixesduplicate,dup- Files marked as duplicatesMultiple language variants (copie, kopia, copia)
Development
Requirements
Python 3.8+
hashlibfor MD5 hashingpathlibfor file path operationsFastMCPfor MCP server implementation
Project Structure
DuplicateListor/
├── duplicatelist.py # Main server implementation
├── main.py # Entry point
├── pyproject.toml # Project configuration
└── README.md # This fileSafety Features
Dry-run Mode: Preview changes before actual deletion
Smart Original Detection: Preserves files without copy indicators
Error Handling: Graceful handling of inaccessible files
Content-based Matching: Uses MD5 hashing for accurate duplicate detection
Detailed Reporting: Comprehensive feedback on all operations
License
MIT License
Available Tools
3 toolsdelete_duplicatesA
Delete duplicate files in a directory, keeping only one copy of each file. Uses intelligent copy detection to prioritize deleting files with copy indicators (like "copy", "(1)", "(2)", etc.) over original files.
Args: directory: Directory path to search for duplicates (default: current directory) recursive: Whether to search recursively in subdirectories (default: True) dry_run: If True, only show what would be deleted without actually deleting (default: True)
Returns: Dictionary with information about deleted files and preserved originals
Example: delete_duplicates(directory="./documents", dry_run=True) # Preview only delete_duplicates(directory="./documents", dry_run=False) # Actually delete
Inputs: dry_run, directory, recursive. Returns: result
find_duplicatesA
Find duplicate files in a directory based on content hash.
Args: directory: Directory path to search for duplicates (default: current directory) recursive: Whether to search recursively in subdirectories (default: True)
Returns: Dictionary with hash as key and list of duplicate file paths as values
Example: find_duplicates(directory="./documents") find_duplicates(directory="/home/user", recursive=False)
Inputs: directory, recursive. Returns: result
list_filesA
List files in a specified directory with optional filtering.
Args: directory: Directory path to list files from (default: current directory) pattern: File pattern to match (e.g., ".py", ".txt") (default: "*") include_hidden: Whether to include hidden files (default: False)
Returns: List of dictionaries containing file information (name, size, type, path)
Example: list_files(directory=".", pattern="*.py") list_files(directory="/home/user/documents", include_hidden=True)
Inputs: pattern, directory, include_hidden. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a distinct purpose: list_files for directory exploration, find_duplicates for identifying duplicates, and delete_duplicates for removing them. There is no overlap or ambiguity between the tool functions.
All tools follow the verb_noun pattern with consistent snake_case and plural nouns (list_files, find_duplicates, delete_duplicates). The naming is uniform and intuitive.
With 3 tools, the server is tightly scoped to the core duplicate file management workflow. Each tool is essential and none are redundant, making the count appropriate.
The tool set covers the full lifecycle: listing files to explore, finding duplicates, and then deleting them with a dry-run option for safety. No critical operations are missing for the stated purpose.
Maintenance
Related MCP Connectors
PDF and image tools for AI agents: compress, merge, split, OCR, sign. Runs locally, never uploads.
Securely search and manage workspace context files for AI agents and teams.
Your own computer's files from ChatGPT or Claude: folder rules, confirmations and undo.
Free deterministic PDF, Markdown, citation, invisible-character, and formatting cleanup for agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides AI assistants with persistent memory through local ChromaDB vector storage, featuring automated file ingestion and batch processing for over 70 file types. It enables advanced vector search, EXIF metadata extraction for photos, and duplicate file detection across local directories.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents and LLMs to perform comprehensive file system operations including CRUD, search, archive, hashing, and duplicate detection via the Model Context Protocol.1MIT
- AlicenseAqualityDmaintenanceEnables AI agents to automatically organize Google Photos and Google Drive files, including deduplication and archiving.635 npmMIT
- AlicenseAqualityDmaintenanceEnables AI agents to explore, analyze, and search file systems, with tools for directory trees, file statistics, duplicate detection, code counting, and multi-criteria file search.545 npmMIT