mcp_server_filesystem

This MCP server provides a clean API for interacting with a local file system within a specified project directory. It exposes operations such as listing directories, reading files, saving or appending content atomically, deleting files, and performing precise edits or moves. It also supports repository-style reference browsing via read-only access to reference projects, enabling an AI assistant to analyze code and project structure without modifying the main workspace. Use the available capabilities to read codebases, generate new files, modify existing content with exact string matches, and perform guided refactors or debugging tasks. When integrated with an MCP client, you can describe the desired file system changes in natural language and the server will execute them inside the restricted project directory, maintaining security and isolation.

Prerequisites:

• Python 3.8+ installed on your system
• Git installed
• Optional: virtual environment tool (venv) available

Installation steps:

1. Clone the repository:

git clone https://github.com/MarcusJellinghaus/mcp_server_filesystem.git
cd mcp_server_filesystem

2. Create and activate a virtual environment (recommended):

python -m venv venv
# macOS/Linux
source venv/bin/activate
# Windows
venv\Scripts\activate

3. Install dependencies in editable mode (via pyproject.toml):

pip install -e .

4. Start the server (example):

mcp-server-filesystem --project-dir /path/to/your/project

Note: The server requires that you specify a project directory with --project-dir for security. You can also add optional reference projects at runtime with --reference-project NAME=PATH and adjust logging with --log-level and --log-file if needed.

Tips and caveats:

• Security: All file operations are restricted to the provided --project-dir. Attempts to escape this directory will be blocked.
• Reference projects: Use --reference-project to provide read-only context from additional directories. Duplicates are auto-renamed (docs, docs_2, docs_3, ...).
• Logging: Structured JSON logs are written to project_dir/logs by default. Use --log-file to override the path. You can enable console-only mode if you do not want file logs.
• Reference discovery: The server supports auto-discovery of reference projects and validates paths on startup.
• CLI usage: The canonical command to run is mcp-server-filesystem with the required --project-dir argument. Other options (like --reference-project and --log-level) are documented in the README.
• Claude Desktop integration: If you integrate with Claude Desktop, ensure the CLI is in PATH and that explicit project paths are provided in the configuration.
• Environment variables: You can customize logging behavior via environment variables (e.g., LOG_DIR, LOG_FORMAT) if supported by your deployment environment.