FilesystemSAFE
ARCHIVED: Pre-harness MCP filesystem experiment. Do not use for new projects; modern agent harnesses provide these capabilities directly.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[!WARNING] Archived. Do not use this project for new work. This was built before modern coding-agent harnesses had good filesystem tools, shell access, scoped editing, and context management. Those harnesses now provide the useful parts of this server directly, without adding another MCP layer. This repository is kept only as a historical reference. I do not recommend installing it, depending on it, or using it as the starting point for a new filesystem integration.
MCP Filesystem Server let an MCP client read, search, and edit files inside explicitly allowed directories. It was designed for early MCP clients that needed 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.
Historical setup
The remaining documentation records how the project worked. These commands are not maintained or recommended for new setups. Published-package installation is not verified.
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=%
aeff4fb3fbeeOBSERVED · 2026-10-07Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control.
claude mcp add mcp-filesystem -- uvx mcp-filesystem
{
"mcpServers": {
"mcp-filesystem": {
"command": "uvx",
"args": [
"mcp-filesystem"
]
}
}
}Exposed tools (21)
16 read · 4 write · 1 destructive. Blast radius: 1 tool can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
calculate_directory_size | read | Calculate the total size of a directory recursively. |
compare_files | read | Compare two text files and show differences. |
create_directory | write | Create a new directory or ensure a directory exists. |
directory_tree | read | Get a recursive tree view of files and directories. |
edit_file | write | Make line-based edits to a text file. |
edit_file_at_line | write | Edit specific lines in a text file. |
find_duplicate_files | read | Find duplicate files by comparing file sizes and contents. |
find_empty_directories | read | Find empty directories. |
find_large_files | read | Find files larger than the specified size. |
get_file_info | read | Retrieve detailed metadata about a file or directory. |
grep_files | read | Search for pattern in files, similar to grep. |
head_file | read | Read the first N lines of a text file. |
list_allowed_directories | read | Returns the list of directories that this server is allowed to access. |
list_directory | read | Get a detailed listing of files and directories in a path. |
move_file | write | Move or rename files and directories. |
read_file | read | Read the complete contents of a file. |
read_file_lines | read | Read specific lines from a text file. |
read_multiple_files | read | Read multiple files at once. |
search_files | read | Recursively search for files and directories matching a pattern. |
tail_file | read | Read the last N lines of a text file. |
write_file | destructive | Create a new file or overwrite an existing file with new content. |
Trust audit
SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | PASS |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (2 observation(s))
- Network
- declared (2 observation(s))
- Shell
- declared (1 observation(s))
- Dependencies
- pinned
- Secrets in source
- none-found
Findings (4)
write_file
.pre-commit-config.yaml
file_hash = hashlib.md5(file_bytes).hexdigest()
"path": "../../../outside/outside.txt",
Gates applied: no_behavioural_pass.
aeff4fb3fbeefull audit observations/trust-audit/mcp-server/safurrier__filesystem-5.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-07 | aeff4fb3fbee | SAFE | B | 89 | first audit |
Questions
What is the Filesystem MCP server?
ARCHIVED: Pre-harness MCP filesystem experiment. Do not use for new projects; modern agent harnesses provide these capabilities directly.
What tools does Filesystem expose?
21 in total: 16 read-only, 4 that write, and 1 that can delete or overwrite (write_file). Every one is listed on this page with its risk.
Is Filesystem safe to connect to an agent?
The audit found nothing in the source that contradicts what it says it does, and graded it B (89/100). Grade A is held back for packages that have also passed a sandboxed behavioural run, which is why a clean server reads B. Separately from the audit: 1 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does Filesystem need?
No credential environment variables were found in its source, so it appears to need none.
How does Filesystem run?
It speaks sse and stdio, so it runs as a local process your client starts. It is published on PyPI as mcp-filesystem.
How current is this page?
The grade is for one exact copy of the source (aeff4fb3fbee), read on 2026-10-07. The repository is watched and re-audited when it changes.