Python (MCP) Filesystem Server

This repository contains a robust Python-based Model Context Protocol (MCP) Filesystem Server. It enables AI models and applications to securely interact with the host system's file directories through a defined set of tools, allowing for operations like reading, writing, moving, and listing files and directories.

The server is built upon the `fastmcp` library and adheres to the Model Context Protocol, providing a standardized way for AI tools to manage and access files within specified boundaries.

It's inspired by this example typescript implementation.

Features

Getting Started

Prerequisites

Installation

1. Clone the repository:

git clone https://github.com/hypercat/PyMCP-FS.git
    cd PyMCP-FS

2. Install dependencies with `uv`:

uv sync

This installs from `uv.lock`, so you get the same versions CI tests against. Pass `--no-dev` to skip the test tooling.

Usage

Running the MCP Server (`main.py`)

The MCP server expects a list of allowed directories as command-line arguments. It will only operate within these specified paths.

python3 main.py -d /path/to/allowed/dir1 /path/to/another/allowed/dir2 --log-level INFO --log-file mcp_server.log

Arguments:

Example:

To allow the server access to your home directory's `projects` folder and a temporary `data` folder:

uv run main.py -d ~/projects /tmp/data --log-level DEBUG --log-file mcp_debug.log

Once running, the server will listen for MCP messages on its standard input (`stdin`) and respond on its standard output (`stdout`).

Running the tests

The suite covers path validation and confinement, the file operation helpers,

the MCP tool functions, and server startup.

uv sync
uv run pytest

`tests/test_path_confinement.py` covers the allowed-directory boundary

specifically, including the sibling-prefix and aliased-directory cases.

`test_mcp_server.py` doubles as an integration check and a debugging aid. It

launches `main.py` as a subprocess, performs the MCP `initialize` handshake

over stdio, and asserts on the response. Run it on its own to see the whole

exchange printed:

uv run test_mcp_server.py

CI runs the full suite on Linux and Windows across Python 3.10, 3.12 and 3.13.

A pull request cannot be merged unless every job passes.

Troubleshooting

If you encounter issues, here's a checklist:

1. Check Command Line Arguments: Ensure you are providing at least one allowed directory to `main.py`. The server will not start without them.

2. Dependencies: Verify the environment is in sync with the lockfile (`uv sync`).

3. Permissions: Make sure the user running the server has read/write permissions for the specified allowed directories and the log file path.

4. Examine Logs (`mcp_debug.log`): The log file (especially with `--log-level DEBUG`) provides the most detailed information about what the server is doing and where it might be failing.

5. MCP Protocol Adherence: Ensure your client is sending well-formed JSON-RPC 2.0 messages according to the MCP specification. The server expects messages on `stdin` and responds on `stdout`.

6. Path Validation Errors: If you see "Access denied" errors, double-check that the requested paths fall strictly within the configured allowed directories. Paths are compared after full resolution, so a symlink is judged by its target, not by where the link sits.

7. `edit_file` Match Issues: If `edit_file` reports that it "Could not find exact match," verify that the `oldText` in your edit operation exactly matches the content in the file, including whitespace and line endings.

Security

Every file operation is confined to the directories passed via `--directories`.

Requested paths and allowed directories are both fully resolved before the

containment check, so symlinks, `..` segments and Windows 8.3 short names

cannot be used to step outside the allowed tree.

That confinement is the security property this project cares about. If you find

a way around it, please report it privately rather than opening an issue. See

SECURITY.md for the reporting channel and scope.

The boundary is only ever as tight as what you allow. Pointing the server at a

sensitive directory, or at `/`, grants the connected model exactly that access.

Extending the Server

This server provides a solid foundation for filesystem interaction. You can extend its capabilities by:

License

Released under the BSD Zero Clause License (0BSD), the most

permissive license approved by the Open Source Initiative. You may use, modify

and redistribute this software for any purpose, with no obligation to preserve

a copyright notice or to ship the license text.