MCP File System Server

You run a local MCP server that exposes file system operations inside a defined project directory. This enables an AI assistant to read, write, edit, move, and delete files, as well as inspect reference projects, all while keeping changes contained to your chosen workspace for safer, productive collaboration.

How to use

To use the File System MCP server, start by installing it and then run it with your preferred project directory. You will interact with it through an MCP client or Claude Desktop integration, issuing high‑level prompts like reading a file, saving changes, or listing directory contents. All actions are constrained to the project directory you specify, ensuring safety and control. You can also attach read‑only reference projects to provide context without risking modifications to your main workspace.

How to install

# Prerequisites
- Python 3.8+ installed on your system
- Access to a terminal/command prompt

# Optional but recommended: create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies in editable mode
pip install -e .

After installation, you are ready to run the server with your project directory. The server enforces that all file operations stay within the specified project directory for security.

## Security and usage notes

- The project directory you specify with --project-dir is required and all file operations are restricted to this directory.
- Attempts to access files outside of the project directory result in an error.
- Reference projects are read‑only and use the same path validation and filtering rules as the main project.
- All file writes are atomic to prevent data corruption, and delete operations are restricted to the project directory.

## Configuration and startup

Run the server using the command shown below. You can include optional reference projects, log level, and log file as needed.

mcp-server-filesystem --project-dir /path/to/your/project
--reference-project docs=/path/to/documentation
--reference-project examples=/path/to/examples
--log-level INFO

If you omit --reference-project, the server starts with just the main project directory.

Reference projects

Reference projects provide read‑only context for the AI assistant. You can add multiple references, which enables browsing surrounding code and documentation without risking edits to those projects.

Claude Desktop integration

You can configure Claude Desktop to connect to this MCP server by adding a configuration entry that points to the mcp-server-filesystem executable and passes the appropriate arguments, including the main project directory and any reference projects.

Troubleshooting

• Verify the mcp-server-filesystem command is available in your PATH and that your project directory exists and is accessible.
• Check that all provided paths for reference projects resolve correctly and are readable.
• Review logs to identify issues with startup, path validation, or permissions.

Security notes

All paths are validated to ensure they remain within the project directory. Reference projects are strictly read‑only. Path traversal attempts are blocked, and file operations are confined to the specified directories.

Usage examples

List files in the project root: ask the MCP client to invoke list_directory. Read a file: request read_file with the path relative to the project. Save a new file: use save_file with the path and content. Edit a file exactly: use edit_file with precise old_text → new_text replacements.

Integrations and tooling

This server uses the MCP protocol to enable local AI collaboration on your file system. It supports operations for reading, writing, appending, deleting, moving, and editing files, along with reference project discovery and file access within context.

Notes on logging and observability

Structured logging is available to capture both human‑readable events and JSON logs for automated processing. You can configure the log level and log file path to suit your debugging and auditing needs.

Shutdown and cleanup

To stop the server, terminate the process in your operating system. Since file writes are atomic and changes are confined to the project directory, you can safely stop the server without risking partial writes or inconsistent state.

Available tools

list_directory

Returns a list of files and directories in the project directory, with gitignore filtering to skip irrelevant paths and exclude .git folders.

read_file

Reads and returns the contents of a file given a path relative to the project directory.

save_file

Writes content to a file atomically, creating or overwriting the target file.

append_file

Appends content to an existing file specified by its path relative to the project directory.

delete_this_file

Deletes a specified file from the project directory with a permanent removal.

edit_file

Makes selective edits using exact string matching with optional dry run and indentation preservation.

move_file

Moves or renames files or directories within the project, creating necessary parent directories and preserving git history where possible.

get_reference_projects

Discovers available read‑only reference projects that can be browsed for context.

list_reference_directory

Lists files in a reference project with the same filtering as the main project.

read_reference_file

Reads files from reference projects in a read-only fashion.