Skip to main content
Glama
filesystem_sandbox

filesystem_sandbox

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: vulcan-file-ops

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.

Available Tools

5 tools
delete_fileA

Delete a file inside the sandbox.

  • Only deletes files (not directories)

  • Path must be relative to the sandbox root

Inputs: relative_path (required). Returns: result

list_filesA

List files and folders inside the allowed sandbox directory.

Rules:

  • All paths are relative to the sandbox root

  • Use "." to list the root of the allowed directory

  • Absolute paths (like "/") are not allowed

Inputs: relative_path (required). Returns: result

list_rootA

List files and folders in the root of the sandbox.

Use this to understand what files are available before organizing or cleaning up the directory.

Use this whenever the user asks what files are available or what files can be seen.

Inputs: no named parameters. Returns: result

make_directoryA

Create a directory inside the sandbox.

  • Path must be relative to the sandbox root

  • Creates parent directories if needed

  • Does nothing if the directory already exists

Inputs: relative_path (required). Returns: result

move_fileA

Move or rename a file within the sandbox.

Both source and destination paths must be relative to the sandbox.

Inputs: dst_relative_path (required), src_relative_path (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 5 tools

    Disambiguation3/5

    list_files and list_root overlap significantly—both list contents of the sandbox, with list_files able to list the root via '.', making list_root redundant. Other tools are distinct, but the boundary between the two listing tools is unclear.

    Naming Consistency5/5

    All tools follow a consistent verb_noun snake_case pattern (list_files, list_root, move_file, make_directory, delete_file), making the set predictable.

    Tool Count5/5

    Five tools is well-scoped for a sandboxed filesystem utility, covering essential operations without bloat.

    Completeness3/5

    The set covers listing, moving, creating directories, and deleting files, but lacks common file operations like reading/writing file contents or deleting directories, leaving notable gaps for a filesystem tool.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      A comprehensive MCP (Model Context Protocol) server for file system operations, providing Claude and other AI assistants with access to local files and directories.
      2
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Zero-dependency MCP server that provides AI models with secure read/write/exec access to local files and directories over HTTP and SSE, designed to be tunneled via ngrok for integration with Claude Web.
      -