mac2win-zip-mcp 1.0.0

MCP Server for creating Windows-compatible ZIP files from macOS

mac2win-zip MCP Server

Create Windows-compatible ZIP files from macOS via MCP

An MCP (Model Context Protocol) server for creating Windows-compatible ZIP files.

This MCP server wraps the functionality of mac2win-zip to create ZIP files that work perfectly on Windows from macOS.

Why mac2win-zip MCP Server?

The Problem

macOS uses NFD (Normalization Form Decomposed) for Unicode filenames, while Windows uses NFC (Normalization Form Composed). When you create a ZIP file on macOS containing files with Unicode characters (like Korean, Japanese, or special characters), Windows users often see garbled filenames.

macOS (ZIP created)	Windows (ZIP opened)
📄 Hello?.pdf	❌ (removed)
📄 안녕하세요 세상.pdf	❌ (removed)

The Solution

This MCP server automatically:

1. Normalizes all filenames from NFD to NFC
2. Removes or replaces Windows-forbidden characters
3. Excludes macOS-specific files (.DS_Store, etc.)
4. Preserves the folder structure

Result: ZIP files that work perfectly on both macOS and Windows!

macOS (ZIP created)	Windows (ZIP opened)
📄 Hello.pdf	✅ Hello.pdf
📄 안녕하세요 세상.pdf	✅ 안녕하세요 세상.pdf

Installation

Quick Install (Recommended)

# Install with uv (creates a global command)
uvx --from git+https://github.com/Wordbe/mac2win-zip-mcp mac2win-zip-mcp

# Or install with pipx
pipx install git+https://github.com/Wordbe/mac2win-zip-mcp

Development Install

# Clone the repository
git clone https://github.com/Wordbe/mac2win-zip-mcp.git
cd mac2win-zip-mcp

# Install in development mode
uv pip install -e ".[dev]"

Usage

MCP Configuration for Claude Desktop

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mac2win-zip": {
      "command": "mac2win-zip-mcp"
    }
  }
}

That's it! No path configuration needed. The command is globally available after installation.

MCP Tools

This server provides the following tools:

create_windows_compatible_zip

Create a Windows-compatible ZIP file from files and/or folders.

Parameters:

• paths (array, required): List of file or folder paths to zip
• output (string, optional): Output ZIP filename (default: "archive.zip")
• working_dir (string, optional): Base directory for relative paths

Example usage:

Create a Windows-compatible ZIP of the current directory

Paths: ["."]
Output: "backup.zip"

validate_zip_for_windows

Validate if a ZIP file is Windows-compatible.

Parameters:

• zip_path (string, required): Path to the ZIP file to validate
• working_dir (string, optional): Base directory for relative path

Example usage:

Check if a ZIP file is Windows-compatible

ZIP Path: "archive.zip"

Example Usage with AI Assistants

Create a ZIP of a folder

Create a Windows-compatible ZIP of my Documents folder containing all PDF files.

The AI assistant will:

1. Call create_windows_compatible_zip with the Documents folder path
2. Return the created ZIP file path and file count

Validate a ZIP file

Check if my-backup.zip is Windows-compatible.

The AI assistant will:

1. Call validate_zip_for_windows with the ZIP file path
2. Return validation results and any issues found

Features

• Unicode Normalization: Converts macOS NFD filenames to Windows-compatible NFC
• Character Sanitization: Removes Windows-forbidden characters (<>:"|?*\)
• Auto Recursive: Automatically includes all subdirectories when zipping folders
• Smart Naming: Creates folder-name.zip by default (no -o needed for single folder)
• Structure Preservation: Maintains original folder hierarchy in ZIP
• Smart Filtering: Excludes hidden files (.DS_Store, etc.)
• Korean Support: Perfect handling of Korean and other Unicode filenames
• MCP Protocol: Works with any MCP-compliant AI assistant (Claude, etc.)

Requirements

• Python 3.10 or higher
• uv (recommended) or pip
• MCP-compatible AI assistant (e.g., Claude Desktop)

License

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

Architecture

This MCP server is a thin wrapper around the mac2win-zip library, exposing its functionality via the Model Context Protocol. This means:

• Single source of truth: Core ZIP creation logic lives in mac2win-zip
• Always in sync: Updates to mac2win-zip automatically benefit this MCP server
• Separation of concerns: CLI tool and MCP server share the same battle-tested code

Related Projects

• mac2win-zip - CLI tool for creating Windows-compatible ZIP files (core library)
• Model Context Protocol - The protocol powering this server

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

Bug Reports

If you discover any bugs, please create an issue on GitHub with:

• Your operating system and version
• Python version
• MCP client information
• Steps to reproduce the bug
• Expected vs actual behavior

Show Your Support

If this project helped you, please give it a star!

---

Made with ❤️ by Wordbe for seamless macOS-Windows file sharing