MCP File System Server

A simple Model Context Protocol (MCP) server providing file system operations. This server offers a clean API for performing file system operations within a specified project directory, following the MCP protocol design.

Overview

This MCP server enables AI assistants like Claude (via Claude Desktop) or other MCP-compatible systems to interact with your local file system. With these capabilities, AI assistants can:

• Read your existing code and project files
• Write new files with generated content
• Update and modify existing files with precision using exact string matching
• Make selective edits to code without rewriting entire files
• Delete files when needed
• Review repositories to provide analysis and recommendations
• Debug and fix issues in your codebase
• Generate complete implementations based on your specifications

All operations are securely contained within your specified project directory, giving you control while enabling powerful AI collaboration on your local files.

By connecting your AI assistant to your filesystem, you can transform your workflow from manual coding to a more intuitive prompting approach - describe what you need in natural language and let the AI generate, modify, and organize code directly in your project files.

Features

• list_directory: List all files and directories in the project directory
• read_file: Read a file, or a line slice via start_line/end_line.
• save_file: Write a file, creating parent directories as needed.
• append_file: Append content to the end of a file
• delete_this_file: Delete a single specified file from the filesystem
• delete_directory: Delete a directory (empty by default, whole tree with recursive=True)
• edit_file: Edit a file by exact string match; replace_all for multiple matches.
• move_file: Move or rename files and directories (git-aware: uses git mv for tracked files, else filesystem move)
• get_reference_projects: Discover available reference projects
• list_reference_directory: List files in reference projects
• read_reference_file: Read a reference-project file, or a line slice via start_line/end_line.
• Structured Logging: Comprehensive logging system with both human-readable and JSON formats

Installation

# Clone the repository
git clone https://github.com/MarcusJellinghaus/mcp-workspace.git
cd mcp_workspace

# Create and activate a virtual environment (optional but recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies using pip with pyproject.toml
pip install -e .

Running the Server

Once installed, you can use the mcp-workspace command directly:

mcp-workspace --project-dir /path/to/project [--reference-project NAME=/path/to/reference]... [--log-level LEVEL] [--log-file PATH] [--file-size-limit N]

Command Line Arguments:

• --project-dir: (Required) Directory to serve files from
• --reference-project: (Optional) Add reference project in format name=/path/to/dir (repeatable, auto-renames duplicates)
• --log-level: (Optional) Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
• --log-file: (Optional) Path for structured JSON logs. If not specified, logs to mcp_workspace_{timestamp}.log in project_dir/logs/.
• --file-size-limit: (Optional) Default line limit for check_file_size when max_lines is omitted; must be > 0. Falls back to 600 when not set.

The server uses FastMCP for operation. The project directory parameter (--project-dir) is required for security reasons. All file operations will be restricted to this directory. Attempts to access files outside this directory will result in an error.

Structured Logging

The server provides flexible logging options:

• Standard human-readable logs to console
• Structured JSON logs to file (default: project_dir/logs/mcp_workspace_{timestamp}.log or custom path with --log-file)
• Function call tracking with pa

... View full README on GitHub