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

Related MCP server: file-system-mcp-server

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/sandbox

All 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/sandbox

The 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.