awaybreaktoday/mcp-filesystem-cross-platform

Cross-Platform Filesystem MCP Server

A comprehensive filesystem MCP server that works across Linux, macOS, and Windows platforms with intelligent platform-specific adaptations.

🌍 Platform Support

✅ Supported Platforms

• Linux - Full support with Unix-style commands
• macOS - Full support with Unix-style commands
• Windows - Full support with Windows-specific commands
• FreeBSD/OpenBSD - Basic support

🔧 Platform-Specific Features

Linux (/home/, /tmp/, /opt/, /usr/local/, /etc/)

• Uses find for file search
• Unix-style permissions and ownership
• Standard shell commands via /bin/bash
• Package manager paths included

macOS (/Users/, /tmp/, /opt/homebrew/, /usr/local/)

• Uses find for file search
• Unix-style permissions and ownership
• Homebrew paths for both Intel and Apple Silicon
• Standard shell commands via /bin/bash

Windows (C:\Users\, C:\temp\, C:\tmp\, D:\)

• Uses dir for file search with recursion
• Windows-style paths and permissions
• Commands via cmd.exe
• Multiple drive support

🛠️ Available Tools

Core Filesystem Operations

• get_platform_info - Show current platform and allowed paths
• list_directory - List directory contents with platform-aware hidden file filtering
• read_file / write_file - File content operations
• create_directory / delete_directory - Directory management
• delete_file - File removal
• move_item / copy_item - File/directory manipulation
• get_file_info - Detailed file metadata (platform-specific)

Search & Navigation

• search_files - Platform-aware file search (find/dir)
• get_current_directory - Current working directory info
• execute_command - Platform-aware shell command execution

🚀 Quick Setup

1. Install Dependencies

cd mcp-filesystem-cross-platform
npm install

2. Build (Optional)

npm run build

3. Run Development Mode

npm run dev

4. Install to a Runtime Directory (Optional)

./scripts/install-runtime.sh

By default the script installs the server into /opt/mcp-servers/mcp-filesystem-cross-platform. Use --prefix to change the parent directory or --name to customize the folder name.

📋 Platform-Specific Allowed Paths

The MCP automatically detects the platform and restricts access to safe directories:

Linux

/home/          # User directories
/tmp/           # Temporary files  
/var/tmp/       # System temporary
/opt/           # Optional software
/usr/local/     # Local installations
/etc/           # Configuration files (read access)

macOS

/Users/         # User directories
/tmp/           # Temporary files
/var/tmp/       # System temporary  
/opt/homebrew/  # Homebrew (Apple Silicon)
/usr/local/     # Homebrew (Intel) + local installations

Windows

C:\Users\       # User directories
C:\temp\        # Temporary files
C:\tmp\         # Alternative temp
D:\             # Additional drives

🔒 Security Features

• Path validation prevents directory traversal attacks
• Platform-aware restrictions to system-appropriate safe directories
• Sandboxed execution environment
• No access to system-critical directories outside allowed paths

⚙️ Claude Desktop Configuration

Linux/macOS

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-filesystem-cross-platform/src/index.ts"]
    }
  }
}

Windows

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["tsx", "C:\\path\\to\\mcp-filesystem-cross-platform\\src\\index.ts"]
    }
  }
}

🎯 Usage Examples

Once configured, you can ask Claude:

Platform Detection

• "What platform am I running on?"
• "Show me the allowed filesystem paths"

File Operations

• "List the contents of my home directory"
• "Create a new directory called 'projects'"
• "Read the contents of my .bashrc file" (Linux/macOS)
• "Search for all .js files in my projects folder"

Cross-Platform Commands

• "Run 'ls -la'" (Linux/macOS) or "Run 'dir'" (Windows)
• "Execute 'npm install' in my project directory"

🔄 Differences from macOS-Only Version

Improvements:

• ✅ Cross-platform compatibility (Linux, macOS, Windows)
• ✅ Platform-aware command execution (find vs dir)
• ✅ Intelligent path restrictions based on OS
• ✅ Better error handling for platform differences
• ✅ Platform detection and reporting

Key Changes:

• Uses os.platform() for platform detection
• Platform-specific allowed paths arrays
• Different search commands per platform (find vs dir)
• Platform-aware shell selection (bash vs cmd.exe)
• Windows drive letter support
• Enhanced hidden file filtering (includes $ files on Windows)

🐧 Linux-Specific Notes

The filesystem MCP works excellently on Linux with these considerations:

• Package Management: Can access /opt/ and /usr/local/ for installed software
• Configuration: Read access to /etc/ for system configs
• Permissions: Full Unix permissions and ownership support
• Shell: Uses /bin/bash for command execution
• Temporary Files: Supports both /tmp/ and /var/tmp/

💻 Windows-Specific Notes

Full Windows support with these adaptations:

• Drive Letters: Supports multiple drives (C:, D:, etc.)
• Path Separators: Handles Windows backslashes correctly
• Commands: Uses cmd.exe and Windows-native commands
• Hidden Files: Filters both . and $ prefixed files
• Permissions: Windows-style file attributes

🚀 Migration from macOS-Only Version

If you're currently using the macOS-only version, here's how to migrate:

1. Update your Claude Desktop config:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-filesystem-cross-platform/src/index.ts"]
    }
  }
}

2. Test platform detection:

Ask Claude: "What platform am I running on?" to verify it's working.

3. Benefits you'll gain:

• Future-proof for Linux servers/containers
• Better Windows compatibility if needed
• More robust error handling
• Platform-aware command suggestions

🐛 Troubleshooting

Common Issues:

1. Permission Denied

   • Check that the path is within allowed directories
   • Use "get platform info" to see allowed paths

2. Command Not Found

   • Commands are platform-specific (use ls on Unix, dir on Windows)
   • MCP will suggest appropriate commands for your platform

3. Path Not Found

   • Use forward slashes / on all platforms (Node.js handles conversion)
   • Check path exists with "list directory" first

This cross-platform version provides excellent Linux support with full compatibility for Linux-specific paths, permissions, and shell commands. The original macOS version would have failed on Linux due to hardcoded /Users/ paths and macOS-specific assumptions.