mcp-filesystem MCP Server

MCP Filesystem Server

Status: This project is no longer under active development. It was useful when MCP clients and agent harnesses were still early and did not yet have good built-in file search or filesystem interaction. Modern clients may already cover much of what this server provides.

MCP Filesystem Server lets an MCP client read, search, and edit files inside directories you explicitly allow. It is useful when Claude Desktop or another MCP client needs filesystem access with path sandboxing, line-range reads, grep-style search, and edit previews.

The server does not grant whole-disk access. At startup you pass one or more allowed directories; every tool call is validated against those roots.

Quick start from a source checkout

This README documents running the server from this repository. Published-package installation is not verified here.

git clone https://github.com/safurrier/mcp-filesystem.git
cd mcp-filesystem
uv sync --frozen
uv run run_server.py --version

Success signal:

MCP Filesystem Server v0.2.0
A Model Context Protocol server for filesystem operations

uv sync --frozen installs the locked dependencies into .venv in the checkout.

To see the command-line options without starting an MCP session:

uv run run_server.py --help

The main entry points in this repo are:

uv run run_server.py ... — direct script used by tests and the Claude Desktop examples below.
uv run mcp-filesystem ... — installed console script with the same Typer CLI.

Connect it to Claude Desktop

Use absolute paths for both the repository and the directories you want the server to access:

REPO_PATH=$(pwd)
PROJECTS_PATH=$(cd ~/Projects && pwd)
DOCUMENTS_PATH=$(cd ~/Documents && pwd)
printf 'repo=%s\nprojects=%s\ndocuments=%s\n' "$REPO_PATH" "$PROJECTS_PATH" "$DOCUMENTS_PATH"

Edit Claude Desktop's config file:

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

Add one server entry, replacing the example paths with your own absolute paths:

{
  "mcpServers": {
    "mcp-filesystem": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-filesystem",
        "run",
        "run_server.py",
        "/absolute/path/to/allowed-dir-1",
        "/absolute/path/to/allowed-dir-2"
      ]
    }
  }
}

Restart Claude Desktop after saving the file.

Claude-side success signals:

The MCP server named mcp-filesystem appears in Claude Desktop's MCP tools.
The tool list includes list_allowed_directories, read_file, grep_files, and edit_file_at_line.
Calling list_allowed_directories returns only the directories you passed in the config.

If the server does not appear, watch the Claude Desktop MCP log:

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

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

Run the server manually

The server uses stdio by default, which is what MCP clients such as Claude Desktop expect:

uv run run_server.py /absolute/path/to/dir1 /absolute/path/to/dir2

If you do not pass directories, the server allows the current working directory.

Options verified from the CLI:

Option	Meaning
`--transport`, `-t`	Transport protocol. Default: `stdio`. Use `sse` for SSE.
`--port`, `-p`	Port for SSE transport. Default: `8000`.
`--debug`, `-d`	Enable debug logging through `FASTMCP_LOG_LEVEL=DEBUG`.
`--version`, `-v`	Print version information and exit.
`--help`	Print CLI help and exit.

For MCP Inspector testing, run from a checkout:

npx @modelcontextprotocol/inspector uv run run_server.py /absolute/path/to/test-dir

The Inspector command may download Node packages through npx if they are not already installed.

How access control works

Allowed roots come from positional CLI arguments, or from MCP_ALLOWED_DIRS when the CLI sets it.
If neither is set, the current working directory is the only allowed root.
Paths are validated before filesystem operations run.
Symlinks are checked so a path inside an allowed root cannot point outside it.
The server runs with the operating-system permissions of the user that started it.

Practical rule: pass the narrowest directory that contains the files you want Claude to work with. Do not pass /, your full home directory, or a secrets directory unless you mean to expose it to the MCP client.

MCP tools

Tool names below are taken from mcp_filesystem/server.py.

Discovery and read-only file access

Tool	Use it for
`list_allowed_directories`	Show the sandbox roots available to this server process.
`list_directory`	List files and directories, with optional hidden-file and pattern filtering.
`get_file_info`	Return file or directory metadata.
`read_file`	Read one complete file.
`read_multiple_files`	Read several complete files in one tool call.
`read_file_lines`	Read a line range with `offset` and `limit`.
`head_file`	Read the first N lines of a text file.
`tail_file`	Read the last N lines of a text file.
`directory_tree`	Return a recursive directory tree with depth and pattern controls.

Search

Tool	Use it for
`grep_files`	Search file contents with literal or regex matching, context lines, pagination, size limits, and optional JSON output. Uses ripgrep when available and falls back to Python.
`search_files`	Find files or directories by glob pattern, optionally requiring content matches.

Mutating filesystem operations

Tool	Use it for
`write_file`	Create or overwrite a file. Can create parent directories when requested.
`create_directory`	Create a directory, optionally including parents.
`move_file`	Move or rename a file or directory.
`edit_file`	Apply old-text/new-text edits and return a git-style diff. Supports `dry_run`.
`edit_file_at_line`	Apply line-targeted edits. Supports verification, relative line numbers, abort-on-verification-failure, and `dry_run`.

Start mutating work with dry_run: true where the tool supports it. For write_file, create_directory, and move_file, choose a temporary test directory first if you are checking behavior.

Analysis and cleanup helpers

Tool	Use it for
`calculate_directory_size`	Calculate directory size as human-readable text, bytes, or JSON.
`find_duplicate_files`	Find duplicate files by size and content hash.
`compare_files`	Compare two text files and return similarity plus diff output.
`find_large_files`	Find files above a size threshold.
`find_empty_directories`	Find empty directories.

These helpers can scan many files. Use narrow allowed directories and result limits for large trees.

Common workflows

Read a specific part of a large file

Use grep_files to find a match, then read_file_lines to inspect the surrounding range. read_file_lines uses a 0-based offset and a maximum limit.

{
  "path": "/absolute/path/to/file.log",
  "offset": 1200,
  "limit": 80,
  "encoding": "utf-8"
}

Search with context and pagination

{
  "path": "/absolute/path/to/project",
  "pattern": "def main",
  "is_regex": false,
  "context_before": 2,
  "context_after": 4,
  "include_patterns": ["*.py"],
  "results_offset": 0,
  "results_limit": 20
}

Preview a line-targeted edit

{
  "path": "/absolute/path/to/file.txt",
  "line_edits": [
    {
      "line_number": 15,
      "action": "replace",
      "content": "replacement text\n",
      "expected_content": "old text\n"
    }
  ],
  "abort_on_verification_failure": true,
  "dry_run": true
}

Then repeat with dry_run: false only after the preview is correct.

Development

Set up the checkout:

uv sync --frozen --all-extras

Run focused checks while editing:

uv run -m pytest tests/test_cli.py
uv run -m pytest tests/test_server_unit.py
uv run -m ruff check mcp_filesystem tests
uv run -m mypy mcp_filesystem

The Makefile also provides maintainer workflows:

make setup   # compiles requirements, creates .venv, syncs deps, installs pre-commit hooks
make check   # setup, lint with --fix, format, tests with coverage, mypy

make check mutates local files because it may update requirements, install hooks, apply Ruff fixes, and write coverage data.

Troubleshooting

Claude Desktop cannot start the server

Do this:

Run uv run run_server.py --version from the checkout.
Confirm the Claude config uses an absolute path after --directory.
Confirm every allowed directory path is absolute and exists.
Check the Claude MCP log shown above.

Do not use relative paths in the Claude config; they may be resolved relative to the client process, not this repository.

A file outside the allowed directory is rejected

That is expected. Restart the MCP server with the narrowest additional allowed root that contains the file.

Search is slower than expected

Install ripgrep (rg). The server uses ripgrep when it is available and falls back to Python search otherwise.

A mutating tool changed the wrong file

Prefer edit_file_at_line with expected_content, abort_on_verification_failure: true, and dry_run: true before applying changes. For whole-file replacement, use read_file or get_file_info first so the client has the current path and content.

MCP Filesystem Server

Status: This project is no longer under active development. It was useful when MCP clients and agent harnesses were still early and did not yet have good built-in file search or filesystem interaction. Modern clients may already cover much of what this server provides.

The server does not grant whole-disk access. At startup you pass one or more allowed directories; every tool call is validated against those roots.

Quick start from a source checkout

This README documents running the server from this repository. Published-package installation is not verified here.

git clone https://github.com/safurrier/mcp-filesystem.git
cd mcp-filesystem
uv sync --frozen
uv run run_server.py --version

Success signal:

MCP Filesystem Server v0.2.0
A Model Context Protocol server for filesystem operations

uv sync --frozen installs the locked dependencies into .venv in the checkout.

To see the command-line options without starting an MCP session:

uv run run_server.py --help

The main entry points in this repo are:

uv run run_server.py ... — direct script used by tests and the Claude Desktop examples below.
uv run mcp-filesystem ... — installed console script with the same Typer CLI.

Connect it to Claude Desktop

Use absolute paths for both the repository and the directories you want the server to access:

REPO_PATH=$(pwd)
PROJECTS_PATH=$(cd ~/Projects && pwd)
DOCUMENTS_PATH=$(cd ~/Documents && pwd)
printf 'repo=%s\nprojects=%s\ndocuments=%s\n' "$REPO_PATH" "$PROJECTS_PATH" "$DOCUMENTS_PATH"

Edit Claude Desktop's config file:

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

Add one server entry, replacing the example paths with your own absolute paths:

{
  "mcpServers": {
    "mcp-filesystem": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-filesystem",
        "run",
        "run_server.py",
        "/absolute/path/to/allowed-dir-1",
        "/absolute/path/to/allowed-dir-2"
      ]
    }
  }
}

Restart Claude Desktop after saving the file.

Claude-side success signals:

The MCP server named mcp-filesystem appears in Claude Desktop's MCP tools.
The tool list includes list_allowed_directories, read_file, grep_files, and edit_file_at_line.
Calling list_allowed_directories returns only the directories you passed in the config.

If the server does not appear, watch the Claude Desktop MCP log:

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

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

Run the server manually

The server uses stdio by default, which is what MCP clients such as Claude Desktop expect:

uv run run_server.py /absolute/path/to/dir1 /absolute/path/to/dir2

If you do not pass directories, the server allows the current working directory.

Options verified from the CLI:

Option	Meaning
`--transport`, `-t`	Transport protocol. Default: `stdio`. Use `sse` for SSE.
`--port`, `-p`	Port for SSE transport. Default: `8000`.
`--debug`, `-d`	Enable debug logging through `FASTMCP_LOG_LEVEL=DEBUG`.
`--version`, `-v`	Print version information and exit.
`--help`	Print CLI help and exit.

For MCP Inspector testing, run from a checkout:

npx @modelcontextprotocol/inspector uv run run_server.py /absolute/path/to/test-dir

The Inspector command may download Node packages through npx if they are not already installed.

How access control works

Allowed roots come from positional CLI arguments, or from MCP_ALLOWED_DIRS when the CLI sets it.
If neither is set, the current working directory is the only allowed root.
Paths are validated before filesystem operations run.
Symlinks are checked so a path inside an allowed root cannot point outside it.
The server runs with the operating-system permissions of the user that started it.

MCP tools

Tool names below are taken from mcp_filesystem/server.py.

Discovery and read-only file access

Tool	Use it for
`list_allowed_directories`	Show the sandbox roots available to this server process.
`list_directory`	List files and directories, with optional hidden-file and pattern filtering.
`get_file_info`	Return file or directory metadata.
`read_file`	Read one complete file.
`read_multiple_files`	Read several complete files in one tool call.
`read_file_lines`	Read a line range with `offset` and `limit`.
`head_file`	Read the first N lines of a text file.
`tail_file`	Read the last N lines of a text file.
`directory_tree`	Return a recursive directory tree with depth and pattern controls.

Search

Tool	Use it for
`grep_files`	Search file contents with literal or regex matching, context lines, pagination, size limits, and optional JSON output. Uses ripgrep when available and falls back to Python.
`search_files`	Find files or directories by glob pattern, optionally requiring content matches.

Mutating filesystem operations

Tool	Use it for
`write_file`	Create or overwrite a file. Can create parent directories when requested.
`create_directory`	Create a directory, optionally including parents.
`move_file`	Move or rename a file or directory.
`edit_file`	Apply old-text/new-text edits and return a git-style diff. Supports `dry_run`.
`edit_file_at_line`	Apply line-targeted edits. Supports verification, relative line numbers, abort-on-verification-failure, and `dry_run`.

Start mutating work with dry_run: true where the tool supports it. For write_file, create_directory, and move_file, choose a temporary test directory first if you are checking behavior.

Analysis and cleanup helpers

Tool	Use it for
`calculate_directory_size`	Calculate directory size as human-readable text, bytes, or JSON.
`find_duplicate_files`	Find duplicate files by size and content hash.
`compare_files`	Compare two text files and return similarity plus diff output.
`find_large_files`	Find files above a size threshold.
`find_empty_directories`	Find empty directories.

These helpers can scan many files. Use narrow allowed directories and result limits for large trees.

Common workflows

Read a specific part of a large file

Use grep_files to find a match, then read_file_lines to inspect the surrounding range. read_file_lines uses a 0-based offset and a maximum limit.

{
  "path": "/absolute/path/to/file.log",
  "offset": 1200,
  "limit": 80,
  "encoding": "utf-8"
}

Search with context and pagination

{
  "path": "/absolute/path/to/project",
  "pattern": "def main",
  "is_regex": false,
  "context_before": 2,
  "context_after": 4,
  "include_patterns": ["*.py"],
  "results_offset": 0,
  "results_limit": 20
}

Preview a line-targeted edit

{
  "path": "/absolute/path/to/file.txt",
  "line_edits": [
    {
      "line_number": 15,
      "action": "replace",
      "content": "replacement text\n",
      "expected_content": "old text\n"
    }
  ],
  "abort_on_verification_failure": true,
  "dry_run": true
}

Then repeat with dry_run: false only after the preview is correct.

Development

Set up the checkout:

uv sync --frozen --all-extras

Run focused checks while editing:

uv run -m pytest tests/test_cli.py
uv run -m pytest tests/test_server_unit.py
uv run -m ruff check mcp_filesystem tests
uv run -m mypy mcp_filesystem

The Makefile also provides maintainer workflows:

make setup   # compiles requirements, creates .venv, syncs deps, installs pre-commit hooks
make check   # setup, lint with --fix, format, tests with coverage, mypy

make check mutates local files because it may update requirements, install hooks, apply Ruff fixes, and write coverage data.

Troubleshooting

Claude Desktop cannot start the server

Do this:

Run uv run run_server.py --version from the checkout.
Confirm the Claude config uses an absolute path after --directory.
Confirm every allowed directory path is absolute and exists.
Check the Claude MCP log shown above.

Do not use relative paths in the Claude config; they may be resolved relative to the client process, not this repository.

A file outside the allowed directory is rejected

That is expected. Restart the MCP server with the narrowest additional allowed root that contains the file.

Search is slower than expected

Install ripgrep (rg). The server uses ripgrep when it is available and falls back to Python search otherwise.

MCP Filesystem Server

README Documentation

MCP Filesystem Server

Quick start from a source checkout

Connect it to Claude Desktop

Run the server manually

How access control works

MCP tools

Discovery and read-only file access

Search

Mutating filesystem operations

Analysis and cleanup helpers

Common workflows

Read a specific part of a large file

Search with context and pagination

Preview a line-targeted edit

Development

Troubleshooting

Claude Desktop cannot start the server

A file outside the allowed directory is rejected

Search is slower than expected

A mutating tool changed the wrong file

Further reading

Quick Install

Quick Actions

Key Features

MCP Filesystem Server

README Documentation

MCP Filesystem Server

Quick start from a source checkout

Connect it to Claude Desktop

Run the server manually

How access control works

MCP tools

Discovery and read-only file access

Search

Mutating filesystem operations

Analysis and cleanup helpers

Common workflows

Read a specific part of a large file

Search with context and pagination

Preview a line-targeted edit

Development

Troubleshooting

Claude Desktop cannot start the server

A file outside the allowed directory is rejected

Search is slower than expected

A mutating tool changed the wrong file

Further reading

Quick Install

Quick Actions

Key Features