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

• Secure Directory Access: All file operations are strictly confined to a predefined list of allowed directories, preventing unauthorized access to other parts of the filesystem.
• Comprehensive File Operations:
  • read_file: Read the complete contents of a single text file.
  • read_multiple_files: Efficiently read content from multiple files, returning results with clear path references.
  • write_file: Create new files or overwrite existing ones with specified content.
  • edit_file: Apply line-based edits to text files, with an option for a dry run to preview changes as a Git-style diff.
  • create_directory: Create new directories, including nested structures, or ensure their existence.
  • list_directory: Get a detailed listing of files and subdirectories within a given path.
  • directory_tree: Generate a recursive JSON tree structure of files and directories for a clear hierarchical view.
  • move_file: Move or rename files and directories.
  • search_files: Recursively search for files and directories matching a pattern, with optional exclusion patterns.
  • get_file_info: Retrieve detailed metadata (size, timestamps, permissions) about files or directories.
• Dynamic Allowed Directories: Configurable via command-line arguments to specify exactly which directories the server can access.
• Robust Logging: Integrates comprehensive logging with support for different log levels and output to both stderr (for MCP compliance) and an optional rotating log file.
• Error Handling: Provides detailed error messages for common issues like access denied, file not found, or permission errors.
• Line Ending Normalization: Handles \r\n and \n line endings consistently for edit_file operations.
• Symlink Protection: Validates the real path of symlinks to prevent escaping allowed directories.

Getting Started

Prerequisites

• Python 3.8+: The server is developed and tested with modern Python versions.
• fastmcp library: This server uses the fastmcp library for MCP protocol handling. You'll need to install it.

Installation

1. Clone the repository:

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

2. Initialize project with uv:

   uv pip install -r pyproject.toml
   

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:

• -d, --directories: (Required) One or more paths to directories that the server is allowed to access. You can specify multiple directories.
• --log-file: (Optional) Path to a file where server logs will be written. Logs will rotate to prevent excessive file size.
• --log-level: (Optional) Minimum logging level to output. Choices are DEBUG, INFO, WARNING, ERROR. Default is INFO.

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).

Testing the Server with test_mcp_server.py

The test_mcp_server.py script is a utility for verifying the server's initialization and basic functionality. It launches the main.py server as a subprocess, sends an initialize MCP message, and captures the server's output and logs.

uv run test_mcp_server.py

This script will:

1. Create a temporary directory (~/mcp_test) and a test file within it.
2. Launch main.py as a subprocess, granting it access to the temporary directory.
3. Send a standard MCP initialize request to the server.
4. Monitor the server's output (stdout, stderr) for responses and errors.
5. Print the server's debug log (mcp_debug.log) for detailed insights.
6. Clean up the temporary test files and directories.

Interpreting the Test Output:

• Response: {"jsonrpc": "2.0", "result": {}, "id": 1}: This indicates a successful MCP initialize response from your server, confirming it's correctly handling the initial handshake.
• STDOUT / STDERR: Any direct print statements or uncaught exceptions from main.py will appear here. This is your first stop for runtime errors.
• === DEBUG LOG CONTENTS ===: Provides detailed logs from the server process itself. Look for messages indicating successful tool registration, path validation, and any errors during file operations.

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. fastmcp Installation: Verify that the fastmcp library is correctly installed (pip install fastmcp).
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. Remember that symlink targets are also validated.
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.

Extending the Server

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

• Adding More Tools: Implement new @mcp.tool() functions for other filesystem operations (e.g., copy_file, delete_file, checksum_file).
• Integrating with Other Systems: Modify tools to interact with cloud storage, databases, or version control systems, while still presenting a filesystem-like interface.
• Customizing Validation: Enhance the validate_path function with more complex access control rules if needed.