📁 MCP File System Server

A secure, sandboxed file system server for the Model Context Protocol. Read, write, search, and manage files through any MCP-compatible AI client — with path traversal protection, hidden file controls, and size limits.

---

✨ Features

• 🔧 5 Tools: read_file, write_file, list_directory, search_files, get_file_info
• 📄 1 Resource: file://{path} — read files via MCP resource URIs
• 🛡️ Security-First Architecture: Sandbox isolation, path traversal prevention, max size limits
• 🔥 Hidden File Control: Block .hidden files by default, opt-in with --allow-hidden
• 🔍 Glob-Based Search: Search by pattern (*.py, *.md, data_*.csv)
• 📊 Rich Metadata: File size, timestamps, permissions, text/binary detection
• 🖥️ Dual Transport: stdio and Streamable HTTP

---

🚀 Quick Start

# 1. Setup
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 2. Create sandbox and run
mkdir -p /tmp/mcp-sandbox
python filesystem_server.py --sandbox /tmp/mcp-sandbox

---

🛠️ Tools Reference

read_file(path: str) -> str

Read a file and return its contents with metadata (size, modified time, SHA256).

write_file(path: str, content: str) -> str

Write content to a file. Creates parent directories automatically.

list_directory(path: str) -> str

List files and directories with sizes and type indicators.

search_files(pattern: str, base_path: str = "") -> str

Search by glob pattern across the entire sandbox.

get_file_info(path: str) -> str

Get detailed metadata: type, size, timestamps, permissions, text/binary detection.

---

🛡️ Security Controls

--sandbox PATH          # Required: root directory (all operations restricted)
--allow-hidden          # Allow access to .hidden files and directories
--max-size N            # Max file size in MB (default: 10)

Attack Vector	Protection
../../../etc/passwd	❌ Path traversal prevented
~/.ssh/id_rsa	❌ Outside sandbox
.env files	❌ Blocked by default
100GB file read	❌ Size limit (configurable)
Hidden directory listing	❌ Filtered by default

---

📄 Resources

file://{path}

Read a file's raw content via MCP resource protocol.

---

🔌 Connecting to Clients

Claude Desktop

{
  "mcpServers": {
    "filesystem": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/mcp-file-system-server/filesystem_server.py", "--sandbox", "/tmp/mcp-sandbox"]
    }
  }
}

Cursor

Settings → Features → MCP → Add Server:

• Name: filesystem
• Type: command
• Command: python /ABSOLUTE/PATH/mcp-file-system-server/filesystem_server.py --sandbox /tmp/mcp-sandbox

---

📁 Project Structure

mcp-file-system-server/
├── filesystem_server.py   # Main server (FastMCP + security)
├── requirements.txt
├── setup.sh
├── README.md
└── .gitignore

---

🧪 Example Usage

# Read a file
read_file("/tmp/mcp-sandbox/data.txt")
# → "📄 File: /tmp/mcp-sandbox/data.txt\nSize: 1,234 bytes\n..."

# Write a file
write_file("/tmp/mcp-sandbox/output/report.md", "# Report\n\nHello world!")
# → "✅ Written 28 bytes to /tmp/mcp-sandbox/output/report.md"

# Search for Python files
search_files("**/*.py")
# → "🔍 5 file(s) matching **/*.py:\n  📄 scripts/process.py (1,234 bytes)\n..."

---

📜 License

MIT