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.

Path Confinement

Every path is validated against the project directory before any file operation. Validation resolves symlinks and rejects the path if the resolved location lies outside the project directory. A .. segment is rejected outright rather than followed. Reference projects are validated the same way against their own directory.

Two kinds of path are rejected that earlier versions accepted:

• A .. segment anywhere in the path, not only a leading one. read_file("src/../README.md") is rejected; use read_file("README.md").
• A path that leaves the project through a symlink. A symlinked file inside the project whose target is outside it, or an intermediate symlinked directory component, is rejected even though the path contains no ... To read content that lives outside the project, configure it with --reference-project (read-only) or run a second server instance pointed at it.

One limitation: if the operating system cannot resolve a path at all, validation falls back to the lexical checks alone — the path must contain no .. and must lie under the project directory by name — so a symlink pointing outside the project is not detected in that case.

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.
• Cross-repo GitHub access: the GitHub issue, pull request, search and label read tools accept reference_name; issues can also be created, edited and commented on
• 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 parameters, timing, and results
• Automatic error context capture
• Configurable log levels (DEBUG, INFO, WARNING, ERROR, CRITICAL)
• Use --console-only to disable file logging

Reference Projects

Reference projects allow you to provide AI assistants with read-only file access to additional codebases or directories for context and reference. This feature enables the LLM to browse and read files from multiple projects while keeping file writes restricted to the main project directory. A reference project with a configured repository URL can also be reached through the GitHub tools — see Cross-Repo GitHub Access.

Features

• Read-only file access: Reference project files can only be browsed and read from, never modified. Their GitHub issues are a separate matter — see Cross-Repo GitHub Access
• Multiple projects: Configure multiple reference projects simultaneously
• Auto-discovery: LLM can discover available reference projects
• Security: Same path validation and gitignore filtering as main project
• Flexible paths: Supports both relative and absolute paths

Configuration

Use the --reference-project argument to add reference projects:

# Single reference project
mcp-workspace --project-dir ./my-project --reference-project docs=./documentation

# Multiple reference projects
mcp-workspace --project-dir ./my-project \
  --reference-project docs=./documentation \
  --reference-project examples=/home/user/examples \
  --reference-project libs=../shared-libraries

# Absolute paths
mcp-workspace --project-dir /path/to/main/project \
  --reference-project utils=/usr/local/utils \
  --reference-project config=/etc/myapp

Auto-Rename Behavior

If you specify duplicate reference project names, they are automatically renamed with numeric suffixes:

# This configuration:
mcp-workspace --project-dir ./project \
  --reference-project docs=./docs1 \
  --reference-project docs=./docs2 \
  --reference-project docs=./docs3

# Results in these reference project names:
# - docs (points to ./docs1)
# - docs_2 (points to ./docs2)  
# - docs_3 (points to ./docs3)

Startup Validation

The server validates reference projects at startup:

• Valid references: Added successfully and available to the LLM
• Invalid references: Logged as warnings, but server continues with valid ones
• Path resolution: Relative paths are resolved relative to the current working directory

Use Cases

• Documentation browsing: Give the LLM access to project documentation or wikis
• Code examples: Reference example projects or templates
• Shared libraries: Browse common utility libraries or frameworks
• Configuration files: Access system or application configuration directories
• Multi-project development: Work on one project while referencing related projects

Security Notes

• Reference project files are strictly read-only - no write, edit, or delete file operations are possible
• All paths are validated to prevent directory traversal attacks
• Gitignore filtering is automatically applied to hide irrelevant files
• Path access is restricted to the specified reference project directories
• The same rejections described in Path Confinement apply to reference-project paths

Integration Options

This server can be integrated with different Claude interfaces. Each requires a specific configuration.

Claude Desktop App Integration

The Claude Desktop app can also use this file system server.

Configuration Steps for Claude Desktop

1. Locate the Claude Desktop configuration file:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Add the MCP server configuration (create the file if it doesn't exist):

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-workspace",
      "args": [
        "--project-dir",
        "C:\\path\\to\\your\\specific\\project",
        "--reference-project",
        "docs=C:\\path\\to\\documentation",
        "--reference-project",
        "examples=C:\\path\\to\\examples",
        "--log-level",
        "INFO"
      ]
    }
  }
}

3. Configuration notes:

   • The mcp-workspace command should be available in your PATH after installation
   • You must specify an explicit project directory path in --project-dir
   • Replace the project directory path with your actual project path
   • The project directory should be the folder you want Claude to access

4. Restart the Claude Desktop app to apply changes

Troubleshooting Claude Desktop Integration

• Check logs at: %APPDATA%\Claude\logs (Windows) or ~/Library/Application Support/Claude/logs (macOS)
• Verify the mcp-workspace command is available in your PATH (run mcp-workspace --help to test)
• Ensure the specified project directory exists and is accessible
• Verify all paths in your configuration are correct

Contributing

For development setup, testing, and contribution guidelines, see CONTRIBUTING.md.

Available Tools

The server exposes the following MCP tools:

| Operation | Description | Example Prompt | |-----------|-------------|----------------| | list_directory | Lists files and directories in the project directory | "List all files in the src directory" | | read_file | Reads the contents of a file | "Show me the contents of main.js" | | save_file | Creates or overwrites files atomically | "Create a new file called app.js" | | append_file | Adds content to existing files | "Add a function to utils.js" | | delete_this_file | Removes files from the filesystem | "Delete the temporary.txt file" | | delete_directory | Deletes a directory (empty, or a whole tree with recursive) | "Delete the pr_info directory and its contents" | | edit_file | Makes selective edits using exact string matching | "Fix the bug in the fetch function" | | move_file | Moves or renames files/directories (git-aware: uses git mv for tracked files, else filesystem move) | "Rename config.js to settings.js" | | search_files | Searches file contents by regex and/or finds files by glob | "Find where retries are configured" | | get_reference_projects | Lists available reference projects | "What reference projects are available?" | | list_reference_directory | Lists files in a reference project | "List files in the docs reference project" | | read_reference_file | Reads files from reference projects | "Show me the README from the ex