filesystem
3.7
Certified
file_systemsPython server implementing Model Context Protocol (MCP) for filesystem operations.
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 locationcontent(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 editedits(array): List of edit operationsoldText(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 directorypattern(string): Search patternexcludePatterns(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",
]
}
}
}
}
