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.