mirror of https://github.com/VitexSoftware/mcp-server-filesystem.git synced 2026-10-03 21:37:33 +00:00

MCP server exposing Linux filesystem operations as tools, read-only by default

Find a file

CyberVitexus 8998ed358c chore(debian): restrict Publish to Aptly stage to 'aptly' node Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>		2026-09-24 21:45:31 +02:00
debian	chore(debian): restrict Publish to Aptly stage to 'aptly' node	2026-09-24 21:45:31 +02:00
src/mcp_server_filesystem	Add live capability scenario and fail-closed FS_READONLY.	2026-09-21 11:32:40 +02:00
tests	Add live capability scenario and fail-closed FS_READONLY.	2026-09-21 11:32:40 +02:00
.gitignore	init(mcp-server-filesystem): Initial commit of a new MCP server project exposing Linux filesystem operations.	2026-08-21 00:11:41 +02:00
LICENSE	feat(license): add MIT LICENSE and MCP tool security annotations	2026-08-31 12:13:25 +02:00
pyproject.toml	Add live capability scenario and fail-closed FS_READONLY.	2026-09-21 11:32:40 +02:00
README.md	Add live capability scenario and fail-closed FS_READONLY.	2026-09-21 11:32:40 +02:00

README.md

mcp-server-filesystem

MCP server exposing Linux filesystem operations as tools for LLM agents, built with FastMCP. Designed as a lightweight, low-dependency test server for the mcprack MCP proxy/catalog tool.

Configuration

No credentials are needed. All configuration is via environment variables, read once at startup:

Variable	Required	Description
`FS_ROOT`	no	Directory all paths are confined to (default: current working directory at startup)
`FS_READONLY`	no	`true` (default) blocks mutating tools; set to `false` to allow writes/deletes/moves. Empty/unset values are treated as read-only (fail-closed).

All paths given to tools are resolved against FS_ROOT and rejected if they would escape it (via .. or a symlink). This is an application-level boundary, not a hardened sandbox (no chroot/mount namespace).

Tools

Read-only: list_dir, read_file, stat, exists, glob_search.

Mutating (require FS_READONLY=false): write_file, mkdir, delete, move, copy.

Usage

Recommended — Debian package from VitexSoftware repository

sudo curl -fsSL http://repo.vitexsoftware.com/KEY.gpg -o /usr/share/keyrings/vitexsoftware-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/vitexsoftware-archive-keyring.gpg] http://repo.vitexsoftware.com trixie main backports" \
  | sudo tee /etc/apt/sources.list.d/vitexsoftware.list
sudo apt update
sudo apt install mcp-server-filesystem

The backports component is required, not optional: python3-mcp (a python3-fastmcp dependency) needs python3-jsonschema >= 4.20.0, which is newer than the version Debian trixie ships in main — it's only available in backports. Without it, apt install fails with an unmet-dependency error on python3-jsonschema.

This installs python3-fastmcp and mcp-server-filesystem in a single step.

Alternative — pip

pip install -e .
export FS_ROOT=/path/to/sandbox
mcp-server-filesystem

mcprack integration

Command: mcp-server-filesystem
Env: FS_ROOT=/path/to/sandbox, FS_READONLY=false (if writes are needed)

mcprack spawns it as a stdio subprocess and proxies it over HTTP per user.

Development

pytest
python tests/live_capability_scenario.py              # temp sandbox, FS_READONLY=true
python tests/live_capability_scenario.py --allow-writes  # also exercise mutations

The live scenario creates a temporary FS_ROOT, exercises every read tool, verifies path-escape rejection, and confirms mutating tools refuse under read-only mode. No credentials required.

License

MIT — see LICENSE.