home / mcp / mcp-filesystem mcp server

MCP-Filesystem MCP Server

Not just another MCP filesystem. Optimized file operations with smart context management and token-efficient partial reading/editing. Process massive files without overwhelming context limits.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "safurrier-mcp-filesystem": {
      "command": "uv",
      "args": [
        "run",
        "run_server.py",
        "/absolute/path/to/mcp-filesystem",
        "/absolute/path/to/dir1",
        "/absolute/path/to/dir2"
      ]
    }
  }
}

You operate MCP-Filesystem to securely access and manipulate large files and directories with precise, token-efficient interactions. This server provides a rich set of filesystem operations, intelligent context management, and fast search capabilities so you can read, edit, and analyze big data without loading everything into memory.

How to use

You interact with the server through an MCP client. Start the local MCP-Filesystem server, then connect your client to it to perform operations such as reading specific lines, editing content with verification, listing directories, and performing advanced searches with contextual results.

How to install

Prerequisites you need before starting are a Python environment and the ability to run UV (a lightweight asynchronous tooling runner). Ensure you have these installed on your system.

# Install UV if you haven't already
curl -fsSL https://raw.githubusercontent.com/astral-sh/uv/main/install.sh | bash

# Or with pipx
pipx install uv

Configuration and security

The server enforces strict path validation to ensure access is limited to explicitly allowed directories. It protects against path traversal and validates symlinks to prevent exposure beyond authorized paths. Always run the server with directories you intend to access and keep permissions appropriate for the user running the server.

You can configure MCP-Filesystem to run as a local process using UV. Here are example startup commands you can use directly in your environment. Adapt absolute paths to your system.

uv run run_server.py /absolute/path/to/mcp-filesystem /absolute/path/to/dir1 /absolute/path/to/dir2
```

```
uv run run_server.py /path/to/mcp-filesystem/repo /Users/yourusername/Projects /Users/yourusername/Documents

Troubleshooting and tips

Watch server logs to debug requests and verify what Claude or your MCP client is requesting. Use the following commands to tail logs on macOS or Windows.

# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp-server-mcp-filesystem.log

# Windows PowerShell
Get-Content -Path "$env:APPDATA\Claude\Logs\mcp-server-mcp-filesystem.log" -Tail 20 -Wait

Available tools

read_file

Read the full contents of a file.

read_multiple_files

Read multiple files in parallel to reduce round-trips.

write_file

Create a new file or overwrite an existing one.

create_directory

Create a new directory or ensure it exists.

list_directory

Provide a detailed listing of files and subdirectories.

move_file

Move or rename files and directories.

get_file_info

Retrieve detailed metadata for a file or directory.

list_allowed_directories

List directories the server is allowed to access.

read_file_lines

Read specific line ranges with offset/limit parameters.

edit_file_at_line

Make precise edits with content verification and relative line numbers.

head_file

Read the first N lines of a text file.

tail_file

Read the last N lines of a text file.

grep_files

Search patterns with ripgrep integration, context options, and paginated results.

search_files

Search for files by name or pattern with content search.

directory_tree

Get a recursive tree view of files and directories.

calculate_directory_size

Compute the total size of a directory.

find_duplicate_files

Identify duplicate files by comparing content.

compare_files

Show differences between two text files.

find_large_files

Find files exceeding a specified size.

find_empty_directories

Find directories that contain no files.