# 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:
```bash
curl -sSL https://install.python-poetry.org | python3 -
```
2. Install dependencies:
```bash
poetry install
```
3. Activate the virtual environment:
```bash
poetry shell
```
### Using pip
1. Install the required dependencies:
```bash
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:
```bash
# 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:
```bash
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:
```bash
# 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:
```bash
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.