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