filesystem

# Filesystem MCP Server Python server implementing Model Context Protocol (MCP) for filesystem operations. ## Features - Read/write files - Create/list/delete directories - Move files/directories - Search files - Get file metadata **Note**: The server will only allow operations within directories specified via `args`. ## API ### Resources - `file://system`: File system operations interface ### Tools - **read_file** - Read complete contents of a file - Input: `path` (string) - Reads complete file contents with UTF-8 encoding - **read_multiple_files** - Read multiple files simultaneously - Input: `paths` (string[]) - Failed reads won't stop the entire operation - **write_file** - Create new file or overwrite existing (exercise caution with this) - Inputs: - `path` (string): File location - `content` (string): File content - **edit_file** - Make selective edits using advanced pattern matching and formatting - Features: - Line-based and multi-line content matching - Whitespace normalization with indentation preservation - Multiple simultaneous edits with correct positioning - Indentation style detection and preservation - Git-style diff output with context - Preview changes with dry run mode - Inputs: - `path` (string): File to edit - `edits` (array): List of edit operations - `oldText` (string): Text to search for (can be substring) - `newText` (string): Text to replace with - `dryRun` (boolean): Preview changes without applying (default: false) - Returns detailed diff and match information for dry runs, otherwise applies changes - Best Practice: Always use dryRun first to preview changes before applying them - **create_directory** - Create new directory or ensure it exists - Input: `path` (string) - Creates parent directories if needed - Succeeds silently if directory exists - **list_directory** - List directory contents with [FILE] or [DIR] prefixes - Input: `path` (string) - **move_file** - Move or rename files and directories - Inputs: - `source` (string) - `destination` (string) - Fails if destination exists - **search_files** - Recursively search for files/directories - Inputs: - `path` (string): Starting directory - `pattern` (string): Search pattern - `excludePatterns` (string[]): Exclude any patterns. Glob formats are supported. - Case-insensitive matching - Returns full paths to matches - **get_file_info** - Get detailed file/directory metadata - Input: `path` (string) - Returns: - Size - Creation time - Modified time - Access time - Type (file/directory) - Permissions - **list_allowed_directories** - List all directories the server is allowed to access - No input required - Returns: - Directories that this server can read/write from ## Installation ### git + Python ```bash # Clone the repository git clone https://github.com/MarcusJellinghaus/mcp_server_filesystem cd filesystem # Create and activate a virtual environment (optional but recommended) python -m venv .venv source .venv/bin/activate # On Windows: venv\Scripts\activate # Install dependencies using pip with pyproject.toml pip install -e . ``` ## Running the Server Previous instal required ```bash # Enable virtual env source .venv/bin/activate # Run server with allowed paths (paths optional but recommended) python ./src/main.py /path/to/home /path/to/project ``` Alternatively, you can use uvx to run directly from GH repo uv required https://docs.astral.sh/uv/getting-started/installation/ ```bash uvx --from git+https://github.com/javillegasna/filesystem filesystem /Users/username/Desktop ``` ## Usage with Different Platforms ### Claude Desktop ```json { "mcpServers": { "filesystem": { "command": "uvx", "args": [ "--from", "git+https://github.com/javillegasna/filesystem", "filesystem", "/Users/username/Desktop", "/path/to/other/allowed/dir", ] } } } ``` ### vscode ```json { "mcp": { "servers": { "filesystem": { "command": "uvx", "args": [ "--from", "git+https://github.com/javillegasna/filesystem", "filesystem", "/Users/username/Desktop", "/path/to/other/allowed/dir", ] } } } } ```