filesystem-mcp-server-python

mattmorgis/filesystem-mcp-server-python

3.2

If you are the rightful owner of filesystem-mcp-server-python and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Filesystem MCP Server is a Python-based implementation of the Model Context Protocol's filesystem server, designed to provide secure and efficient file management capabilities over MCP.

Tools

  1. read_file

    Return the contents of a file (head / tail supported).

  2. write_file

    Create / overwrite a file with new content.

  3. edit_file

    Apply line-based replacements; returns a git-style diff.

  4. create_directory

    mkdir -p semantics.

  5. list_directory

    One-level listing distinguishing files / directories.

Filesystem MCP Server (Python)

This project aims to be a feature-parity Python port of the original Node.js filesystem published by the Model Context Protocol org.

Quick start

1. Install dependencies (Python 3.12+)

# create & activate a virtual-env (optional but recommended)
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# install runtime + dev dependencies
uv sync

2. Launch the server

uv run main.py /absolute/path/to/allowed/dir1 /another/allowed/dir

You should see something like:

Secure MCP Filesystem Server running on stdio
Allowed directories: ['/absolute/path/to/allowed/dir1', '/another/allowed/dir']

The server now waits on stdin/stdout for MCP messages. You can:

  1. attach an MCP capable client (e.g. Claude Desktop or the mcp CLI)

Available tools

ToolDescription
read_fileReturn the contents of a file (head / tail supported).
read_multiple_filesBatch variant of read_file.
write_fileCreate / overwrite a file with new content.
edit_fileApply line-based replacements; returns a git-style diff.
create_directorymkdir -p semantics.
list_directoryOne-level listing distinguishing files / directories.
list_directory_with_sizesListing + size + summary, sortable by name/size.
directory_treeRecursive JSON tree – handy for LLM context.
move_fileMove or rename a file / directory.
search_filesCase-insensitive glob-less substring search.
get_file_infoStat a path (size, timestamps, permissions, …).
list_allowed_directoriesReturn the server-side sandbox roots.

Development & testing

Run linters, type-checker and tests locally:

# formatting / style
uv run ruff check
uv run ruff format

# static types (strict mode)
uv run mypy .

# pytest with asyncio auto mode
uv run pytest