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

# 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

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

uvx --from git+https://github.com/javillegasna/filesystem filesystem /Users/username/Desktop

Usage with Different Platforms

Claude Desktop

{
  "mcpServers": {
    "filesystem": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/javillegasna/filesystem",
        "filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir",
      ]
    }
  }
}

vscode

{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "uvx",
        "args": [
        "--from",
        "git+https://github.com/javillegasna/filesystem",
        "filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir",
      ]
      }
    }
  }
}