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)
Install Poetry if you haven't already:
curl -sSL https://install.python-poetry.org | python3 -Install dependencies:
poetry installActivate the virtual environment:
poetry shell
Using pip
Install the required dependencies:
pip install -r requirements.txtEnsure the
documents
folder exists in your project directory.
Usage with Claude Desktop
1. Add the server to Claude Desktop
Open Claude Desktop
Go to Settings → MCP Servers
Click "Add Server"
Configure the server:
Name: File Operations
Command:
poetry
(if using Poetry) orpython
Arguments:
run run_server.py
(if using Poetry) orrun_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 foldercontent
(required): Content to write to the filemode
(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 fromsearch_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 folderrecursive
(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
folderDirectory 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
Import errors: Make sure you've installed the requirements:
# Using Poetry poetry install # Using pip pip install -r requirements.txtPermission errors: Ensure the
documents
folder has write permissionsPath issues: The server automatically creates the
documents
folder if it doesn't existClaude Desktop connection: Make sure the working directory in Claude Desktop settings points to your project folder
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:
Edit
mcp_file_server/server.py
to add new tools or modify existing onesModify the
DOCUMENTS_DIR
constant to change the base directoryAll file types are supported by default - no need to modify file type restrictions
Run tests:
poetry run pytest
Format code:
poetry run black .
Sort imports:
poetry run isort .
Using pip
To modify the server:
Edit
mcp_file_server/server.py
to add new tools or modify existing onesModify the
DOCUMENTS_DIR
constant to change the base directoryAll 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.
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables secure file management operations within a documents folder, including reading, writing, listing, deleting files and creating directories. Supports all file types with path validation to prevent access outside the designated documents directory.