SaravanaGuhan/recycle-bin-forensics-mcp

🗑️ Recycle Bin Forensics MCP Server

A professional Model Context Protocol (MCP) server for forensic analysis of Windows Recycle Bin contents. Perfect for digital forensics, system administration, and cybersecurity investigations.

🔍 Features

Core Forensic Capabilities

• 📋 List Recycled Items - Complete inventory with metadata
• 🔍 Advanced Search - Filter by name, type, date range
• 📊 Timeline Analysis - Chronological deletion timeline
• 💾 File Recovery - Safe restoration with integrity
• 📈 Forensic Reports - Export in JSON/CSV formats
• 🔬 Metadata Extraction - File sizes, timestamps, original paths

Technical Features

• Windows $I File Parsing - Native Recycle Bin format support
• Unicode Path Handling - International filename support
• Multi-User Analysis - Cross-SID folder scanning
• Permission Handling - Graceful access control management
• Real-time Analysis - Live system data processing

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/SaravanaGuhan/recycle-bin-forensics-mcp.git
cd recycle-bin-forensics-mcp

2. Install Dependencies

pip install -r requirements.txt

3. Configure MCP Server

For Kiro IDE:

Add to your .kiro/settings/mcp.json:

{
  "mcpServers": {
    "recycle-bin-forensics": {
      "command": "python",
      "args": ["path/to/recycle_bin_server.py"],
      "env": {
        "PYTHONPATH": "path/to/recycle-bin-forensics-mcp"
      },
      "disabled": false,
      "autoApprove": [
        "list_recycled_items",
        "get_item_details",
        "search_recycled_files",
        "analyze_timeline",
        "export_forensic_report"
      ]
    }
  }
}

For Claude Desktop:

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "recycle-bin-forensics": {
      "command": "python",
      "args": ["path/to/recycle_bin_server.py"]
    }
  }
}

4. Test Installation

python test_server.py
python verify_setup.py

🛠️ Available Tools

💬 Usage Examples

With AI Assistants

"List all recycled items"
"Search for PDF files deleted in the last week"
"Generate a forensic timeline of deletions"
"Recover the file with ID HLCQJ6.docx"
"Export a forensic report in CSV format"

Direct API Usage

# List all recycled items
items = await call_tool("list_recycled_items", {})

# Search for specific files
results = await call_tool("search_recycled_files", {
    "query": "confidential",
    "file_type": ".pdf",
    "date_from": "2024-01-01"
})

# Generate timeline
timeline = await call_tool("analyze_timeline", {})

🧪 Testing

Run the comprehensive test suite:

# Basic functionality
python test_server.py

# MCP integration
python test_mcp_simple.py

# Forensic scenarios
python test_forensic_scenarios.py

# Setup verification
python verify_setup.py

📋 Requirements

• OS: Windows 10/11 (Recycle Bin specific)
• Python: 3.8 or higher
• Dependencies: See requirements.txt
• Permissions: Standard user (admin for some advanced features)

🔒 Security & Privacy

• Read-Only Analysis - No modification of original data
• Permission Respect - Graceful handling of access restrictions
• Data Integrity - Maintains forensic chain of custody
• Local Processing - All analysis performed locally

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Built for the Model Context Protocol
• Compatible with Kiro IDE and Claude Desktop
• Inspired by digital forensics best practices

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: See for detailed technical information

⭐ Star this repository if you find it useful!