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:

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:

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:

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:

create_directory

Create a new directory in the documents folder.

Parameters:

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

Example:

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:

Using pip

You can test the server manually by running:

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.