MCP Server Wsl Filesystem

🚀 WSL File System MCP Server

A Node.js server implementing the Model Context Protocol (MCP), specifically designed for the Windows Subsystem for Linux (WSL) environment. This project is a fork of the original File System MCP Server, optimized for performance improvement and support for Linux commands.

🚀 Quick Start

Important Note

⚠️ Important Note

The original project supports accessing WSL files via network paths, for example:

node dist/index.js '\\.\pipe\windows-to-ubuntu'

And the following example configuration is provided:

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["dist/index.js", "\\\\.", "pipe", "windows-to-ubuntu"]
    }
  }
}

✨ Features

Project Introduction

This project is a fork optimized for WSL, with the following main features:

1. Replace the direct Node.js file system calls in the original project with WSL command execution.
2. Add support for specific WSL distributions.
3. Implement path conversion between Windows and Linux.
4. Improve cross - platform compatibility for file content processing.
5. Add functions specifically for WSL management.

Core Features

• Cross - platform File Operations: Achieve interoperability of file operations between Windows and Linux through WSL command execution.
• Distribution Support: You can select a specified WSL distribution (e.g., Ubuntu - 20.04) or use the default distribution.
• Path Conversion: Automatically handle path conversion between Windows and Linux formats.
• Performance Optimization: Specifically optimized for the WSL environment to improve file operation efficiency.

Toolset

The project provides the following functional tools:

Basic File Operations

• Read file content
• Write file content
• Create a directory
• Delete a directory
• Move files/directories
• Copy files/directories

Advanced Features

• File Search and Lookup: Support file search with complex conditions.
• File Attribute Query: Get detailed file information and metadata.
• Permission Management: Set and modify file permissions.
• Compression and Decompression: Support common archive formats (zip, tar.gz, etc.).
• Logging: Provide detailed operation logs.

📦 Installation

General Installation Steps

1. Clone the project repository:

   git clone https://github.com/yourusername/mcp-server-wsl-filesystem.git
   

2. Navigate to the project directory:

   cd mcp-server-wsl-filesystem
   

3. Install dependencies:

   npm install
   

4. Build the TypeScript project:

   npm run build
   

Development Environment Configuration

1. Ensure that Node.js (v14.0.0 or higher) is installed.
2. Verify the version after installation:

   node --version
   npm --version
   

💻 Usage Examples

Running the Server

Before running the server, you must first build the TypeScript project:

npm install
npm run build

Then run the server, specifying the WSL distribution to use (optional) and the directories to expose:

node dist/index.js [--distro=distribution_name] <allowed_directory> [additional_directories...]

• If no distribution is specified, the system's default distribution will be used.
• Multiple directories can be specified for exposure.

Basic Usage

Access the Ubuntu - 20.04 distribution:

node dist/index.js --distro=Ubuntu-20.04 /home/user/documents

Use the default distribution:

node dist/index.js /home/user/documents

Integration with Claude Desktop

Add the following configuration to claude_desktop_config.json:

Option 1: Specify a Specific WSL Distribution

{
  "mcpServers": {
    "wsl-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-wsl-filesystem",
        "--distro=Ubuntu-20.04",
        "/home/user/documents"
      ]
    }
  }
}

Option 2: Use the Default WSL Distribution

{
  "mcpServers": {
    "wsl-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-wsl-filesystem",
        "/home/user/documents"
      ]
    }
  }
}

In the second option, the system will automatically use the default WSL distribution without additional configuration.

Key Differences from the Original Project

This fork has the following optimizations for the WSL environment:

1. Command Execution Replacement: Replace the direct Node.js calls in the original project with WSL command execution.
2. Distribution Support: Add support for specified WSL distributions.
3. Path Conversion Function: Implement automatic path conversion between Windows and Linux.
4. Performance Improvement: Specifically optimized for the WSL environment.

📄 License

The project follows the MIT license. Please refer to the LICENSE file for specific license details.

Contribution Guidelines

Community contributions are welcome! If you find any issues or have suggestions for improvement, please submit Issues or Pull Requests to the repository:

GitHub Repository