# 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
```bash
cd mcp-filesystem-cross-platform
npm install
```
### 2. Build (Optional)
```bash
npm run build
```
### 3. Run Development Mode
```bash
npm run dev
```
### 4. Install to a Runtime Directory (Optional)
```bash
./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
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["tsx", "/path/to/mcp-filesystem-cross-platform/src/index.ts"]
}
}
}
```
### Windows
```json
{
"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:
```json
{
"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.
