ravikant06/file-system-mcp-server

File System Explorer MCP Server

A comprehensive Model Context Protocol (MCP) server that provides AI assistants with safe and secure file system operations. This server enables AI tools to read, write, and manage files within controlled directories.

Features

• Safe File Operations: Read, write, create, delete, copy, and move files/directories
• Security-First: Restricted to user's home directory by default
• Comprehensive Metadata: File information including size, permissions, timestamps, and MIME types
• Async Operations: Built with async/await for optimal performance
• MCP Protocol: Full compliance with Model Context Protocol standards
• Error Handling: Robust error handling with detailed logging

Available Tools

Installation

Prerequisites

• Python 3.8 or higher
• pip (Python package installer)

Setup

1. Clone or download this repository

   git clone <repository-url>
   cd filesystem-mcp-server
   

2. Create a virtual environment

   python3 -m venv py3_file_sys_mcp_env
   source py3_file_sys_mcp_env/bin/activate  # On Windows: py3_file_sys_mcp_env\Scripts\activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Test the installation

   python filesystem_server.py
   

   You should see:

   INFO:__main__:PathValidator initialized with roots: [PosixPath('/Users/your-home')]
   INFO:__main__:Starting File System Explorer MCP Server...
   INFO:__main__:Allowed directories: ['/Users/your-home']
   

Configuration

Claude Desktop Integration

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
    "mcpServers": {
        "filesystem": {
            "command": "/absolute/path/to/your/virtual-env/bin/python",
            "args": ["/absolute/path/to/filesystem_server.py"],
            "env": {}
        }
    }
}

Example for macOS:

{
    "mcpServers": {
        "filesystem": {
            "command": "/Users/username/Workspace/filesystem-mcp-server/py3_file_sys_mcp_env/bin/python",
            "args": ["/Users/username/Workspace/filesystem-mcp-server/filesystem_server.py"],
            "env": {}
        }
    }
}

Security Configuration

By default, the server restricts access to your home directory. To modify allowed directories, edit the allowed_roots variable in filesystem_server.py:

# Line 268 in filesystem_server.py
allowed_roots = [str(Path.home())]  # Default: home directory only
# allowed_roots = ["/Users/username/Documents", "/Users/username/Projects"]  # Custom paths

Usage

Starting the Server

The server runs automatically when Claude Desktop connects to it. For manual testing:

# Activate virtual environment
source py3_file_sys_mcp_env/bin/activate

# Run the server
python filesystem_server.py

Using with Claude Desktop

1. Restart Claude Desktop after updating the configuration
2. The filesystem tools will be available in Claude Desktop
3. You can now ask Claude to:
   • Read files: "Read the contents of my notes.txt file"
   • Write files: "Create a new file called todo.md with my task list"
   • List directories: "Show me what's in my Documents folder"
   • Manage files: "Copy my project files to a backup directory"

Tool Parameters

read_file

• path (required): Path to the file to read
• encoding (optional): File encoding (default: "utf-8")

write_file

• path (required): Path to the file to write
• content (required): Content to write
• encoding (optional): File encoding (default: "utf-8")

list_directory

• path (required): Path to the directory to list
• include_hidden (optional): Include hidden files (default: false)

create_directory

• path (required): Path to the directory to create
• parents (optional): Create parent directories (default: true)

delete_file

• path (required): Path to the file or directory to delete

copy_file

• source (required): Source path
• destination (required): Destination path

move_file

• source (required): Source path
• destination (required): Destination path

get_file_info

• path (required): Path to the file or directory

Security Features

• Path Validation: All paths are validated against allowed root directories
• Permission Checks: File operations respect system permissions
• Error Handling: Comprehensive error handling prevents crashes
• Logging: All operations are logged for audit purposes

Troubleshooting

Common Issues

1. ModuleNotFoundError: Ensure you're using the virtual environment Python in your MCP configuration
2. Permission Denied: Check that the server has access to the requested directories
3. Server Won't Start: Verify all dependencies are installed correctly

Debug Mode

Enable debug logging by modifying the logging level in filesystem_server.py:

# Line 25
logging.basicConfig(level=logging.DEBUG)  # Change from INFO to DEBUG

Testing the Server

# Test import
python -c "import filesystem_server; print('Import successful')"

# Test server startup
python filesystem_server.py &
# Server should start and wait for connections
kill %1  # Stop the test server

Development

Project Structure

filesystem-mcp-server/
├── filesystem_server.py      # Main server implementation
├── requirements.txt          # Python dependencies
├── README.md                # This file
├── run_server.sh            # Shell script wrapper (optional)
└── py3_file_sys_mcp_env/    # Virtual environment (created during setup)

Key Components

• PathValidator: Handles path validation and security
• FileSystemOperations: Core file system operations
• MCP Server: Protocol implementation and tool registration
• Tool Handlers: Individual tool implementations

License

This project is open source. Please check the license file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Support

For issues and questions:

1. Check the troubleshooting section above
2. Review the logs for error messages
3. Ensure your MCP configuration is correct
4. Verify all dependencies are installed

Note: This server is designed for safe file operations within controlled directories. Always review the security configuration before use in production environments.