nandarizkika/mcp-filesystem-server

MCP Filesystem Server

A Model Context Protocol (MCP) server that provides secure file and directory operations for Claude Desktop.

Features

• 📁 List directory contents with detailed information
• 📄 Read text files safely (with size limits)
• ✏️ Write content to files
• 🗂️ Create directories
• 🗑️ Delete files and directories
• 🔍 Get detailed file/directory information
• 🔐 Built-in security with path restrictions

Security Features

• ✅ Path Restrictions: Only allows access to safe, predefined directories
• ✅ File Size Limits: Won't read files larger than 1MB to prevent memory issues
• ✅ Permission Handling: Gracefully handles permission denied errors
• ✅ Path Validation: Prevents directory traversal attacks
• ✅ Safe Operations: All file operations are validated before execution

Tools Available

list_directory

List the contents of a directory with file sizes, types, and modification dates.

Parameters:

• path (required): Directory path to list

Example: "List the contents of my Documents folder"

read_file

Read the contents of a text file (up to 1MB).

Parameters:

• path (required): File path to read

Example: "Read the file at D:\Projects\README.md"

write_file

Write content to a file, creating directories if needed.

Parameters:

• path (required): File path to write to
• content (required): Content to write

Example: "Write 'Hello World' to a file called hello.txt in my Documents"

create_directory

Create a new directory, including parent directories if needed.

Parameters:

• path (required): Directory path to create

Example: "Create a new directory called 'projects' in my Documents"

delete_file

Delete a file or directory (with all contents).

Parameters:

• path (required): Path to delete

Example: "Delete the old test.txt file in my Documents"

get_file_info

Get detailed information about a file or directory.

Parameters:

• path (required): Path to get information about

Example: "Get information about my Downloads folder"

Prerequisites

• Python 3.7+
• Claude Desktop application
• MCP Python package

Installation

1. Clone the repository:

   git clone https://github.com/nandarizkika/mcp-filesystem-server.git
   cd mcp-filesystem-server
   

2. Create a virtual environment:

   python -m venv .venv
   .venv\Scripts\activate  # On Windows
   # or
   source .venv/bin/activate  # On macOS/Linux
   

3. Install dependencies:

   pip install -r requirements.txt
   

Configuration

Default Allowed Directories

The server restricts access to these safe directories by default:

• User home directory and subdirectories
• Documents, Desktop, Downloads folders
• Custom project directories (configurable)

Custom Directory Configuration

You can modify the allowed directories in the MCPFilesystemServer constructor:

# Example: Add custom allowed directories
server = MCPFilesystemServer(allowed_directories=[
    "C:\\Users\\YourName\\Documents",
    "C:\\Users\\YourName\\Desktop",
    "C:\\Users\\YourName\\Downloads",
    "D:\\YourProjectFolder",
    # Add more as needed
])

Claude Desktop Setup

1. Locate your Claude Desktop config file:

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

2. Add the filesystem server configuration:

   {
     "mcpServers": {
       "filesystem": {
         "command": "path/to/your/project/.venv/Scripts/python.exe",
         "args": ["path/to/your/project/filesystem_server.py"]
       }
     }
   }
   

3. Restart Claude Desktop

Testing

Test the server independently:

python test_filesystem.py

Usage Examples

Once configured with Claude Desktop, you can ask natural language questions:

Directory Operations

• "List the contents of my Documents folder"
• "Show me what's in my Downloads directory"
• "What files are in my project folder?"

File Reading

• "Read the file at D:\Projects\README.md"
• "Show me the contents of my config.txt file"
• "What's in my notes.txt file?"

File Writing

• "Write 'Hello World' to a file called hello.txt in my Documents"
• "Create a new file called notes.txt with my project ideas"
• "Save my meeting notes to a file in my Desktop"

Directory Management

• "Create a new directory called 'backup' in my Documents"
• "Make a new folder called 'projects' in my home directory"
• "Create a directory structure for my new project"

File Information

• "Get information about my Downloads folder"
• "Show me the size and details of my project directory"
• "When was my README.md file last modified?"

File Cleanup

• "Delete the old test.txt file in my Documents"
• "Remove the temporary directory I created"
• "Clean up the old backup files"

Project Structure

mcp-filesystem-server/
├── filesystem_server.py       # Main MCP server
├── test_filesystem.py         # Test script
├── requirements.txt           # Python dependencies
├── .gitignore                # Git ignore rules
├── LICENSE                   # MIT License
└── README.md                # This file

Security Considerations

Path Restrictions

• Only predefined directories are accessible
• No access to system directories (C:\Windows, /etc, etc.)
• No access to other users' directories
• Path traversal attempts are blocked

File Size Limits

• Text files are limited to 1MB to prevent memory issues
• Binary files are rejected for reading operations
• Large directory listings are handled efficiently

Permission Handling

• Permission denied errors are handled gracefully
• No sensitive error information is exposed
• Operations fail safely without crashing

Troubleshooting

Common Issues

1. "Access denied" errors:

   • Check if the path is in the allowed directories list
   • Verify you have proper permissions to the directory
   • Ensure the path exists and is accessible

2. "Server disconnected" in Claude:

   • Check that file paths in the config are correct
   • Ensure Python executable path is accurate
   • Restart Claude Desktop after config changes

3. "File too large" errors:

   • The server limits text files to 1MB for safety
   • Use external tools for larger files
   • Consider processing files in chunks

Debug Steps

1. Test the server independently:

   python test_filesystem.py
   

2. Check server logs in Claude Desktop

3. Verify file permissions on your system

4. Test with simple operations first

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the file for details.

Related Projects

• MCP Weather Server - Weather information MCP server
• MCP Specification - Official MCP documentation

Acknowledgments

• Anthropic for Claude and the MCP specification
• MCP community for protocol documentation and examples
• Contributors and users providing feedback and improvements

⚠️ Important: This server provides file system access. Always review and understand the security implications before use in production environments.

Made with ❤️ for the MCP community