# 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:

```bash
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:

```bash
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:

```json
{
  "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.