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 filtering

  • find_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: ChromaDB Local MCP Server

Quickstart

1. Install & Run

Run the MCP Duplicate File Manager Server using uvx:

uvx --from git+https://github.com/deerajd/DuplicateFileRemover-MCP.git mcp-server

2. 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 directory

Find 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 directory

Delete 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 preview

The 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/suffixes

• duplicate, dup - Files marked as duplicates

• Multiple language variants (copie, kopia, copia)

Development

Requirements

• Python 3.8+

• hashlib for MD5 hashing

• pathlib for file path operations

• FastMCP for MCP server implementation

Project Structure

DuplicateListor/
├── duplicatelist.py             # Main server implementation
├── main.py                      # Entry point
├── pyproject.toml               # Project configuration
└── README.md                    # This file

Safety 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