MCP File Operations Server

A Python MCP (Model Context Protocol) server that provides read and write access to files in the documents subfolder for use with Claude Desktop.

Features

• Read files: Read the contents of any file in the documents folder
• Write files: Create or overwrite files in the documents folder
• List files: Browse files and directories in the documents folder with search capabilities
• Delete files/directories: Remove files or directories from the documents folder
• Create directories: Create new directories within the documents folder
• Security: Path validation to prevent access outside the documents folder
• All file types: Supports all file types without restrictions
• Search functionality: Find files using patterns and recursive search

Installation

Using Poetry (Recommended)

1. Install Poetry if you haven't already:

   curl -sSL https://install.python-poetry.org | python3 -
   

2. Install dependencies:

   poetry install
   

3. Activate the virtual environment:

   poetry shell
   

Using pip

1. Install the required dependencies:

   pip install -r requirements.txt
   

2. Ensure the documents folder exists in your project directory.

Usage with Claude Desktop

1. Add the server to Claude Desktop

1. Open Claude Desktop
2. Go to Settings → MCP Servers
3. Click "Add Server"
4. Configure the server:
   • Name: File Operations
   • Command: poetry (if using Poetry) or python
   • Arguments: run run_server.py (if using Poetry) or run_server.py (if using pip)
   • Working Directory: Path to your project folder

2. Available Tools

Once connected, Claude will have access to these tools:

read_file

Read the contents of a file from the documents folder.

Parameters:

• file_path (required): Path to the file relative to the documents folder

Example:

Read the file "notes.txt" from the documents folder

write_file

Write content to a file in the documents folder.

Parameters:

• file_path (required): Path to the file relative to the documents folder
• content (required): Content to write to the file
• mode (optional): Write mode - "w" for overwrite (default), "a" for append

Example:

Write "Hello World" to a file called "greeting.txt"

list_files

List all files and directories in the documents folder with search capabilities.

Parameters:

• subdirectory (optional): Specific subdirectory to list files from
• search_pattern (optional): Search pattern to filter files (supports wildcards like *.txt, *.py, etc.)
• recursive (optional): Whether to search recursively in subdirectories (default: false)

Examples:

List all files in the documents folder
List all Python files recursively
List all files in the "projects" subdirectory
Search for files matching "*.md" pattern

delete_file

Delete a file or directory from the documents folder.

Parameters:

• file_path (required): Path to the file or directory relative to the documents folder
• recursive (optional): Whether to delete directories recursively (default: false)

Examples:

Delete the file "old_notes.txt"
Delete the directory "temp_folder" recursively

create_directory

Create a new directory in the documents folder.

Parameters:

• dir_path (required): Path to the directory relative to the documents folder

Example:

Create a directory called "projects"

Security Features

• Path validation: All file operations are restricted to the documents folder
• Directory traversal protection: Prevents access to parent directories
• All file types supported: No restrictions on file extensions
• Error handling: Comprehensive error messages for debugging

Supported File Types

The server supports all file types without any restrictions. You can read, write, and manage any file format including:

• Text files (.txt, .md, .py, .js, .html, .css, etc.)
• Data files (.json, .csv, .xml, .yaml, etc.)
• Binary files (.pdf, .doc, .xls, .zip, etc.)
• Images (.jpg, .png, .gif, etc.)
• And any other file type

Testing the Server

Using Poetry

You can test the server using Poetry:

# Run the server directly
poetry run python run_server.py

# Run tests
poetry run pytest

# Run tests with coverage
poetry run pytest --cov=mcp_file_server

Using pip

You can test the server manually by running:

python run_server.py

The server will start and wait for MCP protocol messages on stdin/stdout.

Troubleshooting

Common Issues

1. Import errors: Make sure you've installed the requirements:

   # Using Poetry
   poetry install
   
   # Using pip
   pip install -r requirements.txt
   

2. Permission errors: Ensure the documents folder has write permissions

3. Path issues: The server automatically creates the documents folder if it doesn't exist

4. Claude Desktop connection: Make sure the working directory in Claude Desktop settings points to your project folder

5. Poetry not found: Install Poetry using the official installer:

   curl -sSL https://install.python-poetry.org | python3 -
   

Logging

The server includes logging to help debug issues. Check the console output for error messages.

Development

Using Poetry

To modify the server:

1. Edit mcp_file_server/server.py to add new tools or modify existing ones
2. Modify the DOCUMENTS_DIR constant to change the base directory
3. All file types are supported by default - no need to modify file type restrictions
4. Run tests: poetry run pytest
5. Format code: poetry run black .
6. Sort imports: poetry run isort .

Using pip

To modify the server:

1. Edit mcp_file_server/server.py to add new tools or modify existing ones
2. Modify the DOCUMENTS_DIR constant to change the base directory
3. All file types are supported by default - no need to modify file type restrictions

License

This project is open source and available under the MIT License.