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:
- Install dependencies:
- Activate the virtual environment:
Using pip
- Install the required dependencies:
- Ensure 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
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
- Import errors: Make sure you've installed the requirements:
- Permission errors: Ensure the
documents
folder has write permissions - Path issues: The server automatically creates the
documents
folder if it doesn't exist - Claude 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:
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 ones - Modify the
DOCUMENTS_DIR
constant to change the base directory - All 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 ones - Modify the
DOCUMENTS_DIR
constant to change the base directory - 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.
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.