mcp-server

# 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.