MCP Filesystem Sandbox
A simple, safe, Python MCP server that exposes filesystem operations (list files, move files, create directories, delete files) inside a single sandboxed directory.
The server is designed for learning and personal use with Claude Desktop via the Model Context Protocol (MCP).
---
Features
- Relative-path sandboxing (no access outside the allowed directory)
- No shell execution (pure Python filesystem APIs)
- Safe file-only deletion (directories cannot be deleted)
- Minimal, explicit tool surface
- Designed for use with Claude Desktop via MCP
---
Sandbox directory
This server operates inside one sandbox directory.
You must provide the sandbox path as the first argument when starting the server:
uv run server.py /absolute/path/to/sandboxAll filesystem operations are restricted to this directory. Paths passed to tools are always relative to the sandbox root.
Use "." to refer to the sandbox root itself.
---
Running the server
From the project directory:
uv run server.py /absolute/path/to/sandboxThe server will start and wait for MCP tool calls over stdio. No output is expected while it is running.
---
Using with Claude Desktop (MCP)
Example MCP configuration:
{
"mcpServers": {
"filesystem_sandbox": {
"command": "uv",
"args": [
"--directory",
"/path/to/project",
"run",
"server.py",
"/absolute/path/to/sandbox"
]
}
}
}After updating the configuration, restart Claude Desktop.
Note: Depending on your system, you may need to use the full path to the uv executable (for example /Users/you/.local/bin/uv) instead of uv in the MCP configuration.
---
Safety notes
- All paths are resolved relative to the sandbox directory
- Absolute paths and directory traversal (
..) are blocked - Directories cannot be deleted
- No shell commands are executed
This server is intended for safe experimentation and learning.
