Skip to main content
Glama
MCP Simple Shell

MCP Simple Shell

by TheWandrr

MCP Simple Shell

A workspace-confined file operations server for the Model Context Protocol (MCP). Provides safe, sandboxed file and directory operations with built-in safety features.

Features

  • File Operations: Read, write, copy, move, delete, append, rename, touch, stat

  • Directory Operations: Create, delete, copy, move, rename, list

  • Text Processing: Replace sections, apply unified diff patches

  • Binary Operations: Read/write binary, hexdump, find byte patterns, diff binaries

  • Advanced Processing: UPX unpacking, XOR/AES decryption, YARA scanning, file type detection, firmware carving, entropy analysis, ELF/PE segment splitting

  • SQLite Database: Create, open, query, schema inspection

  • System Tools: Cryptographic hashing, PE rebasing, disk usage, server info

  • Trash System: Protected trash with SHA256 verification for recovery

  • Advisory Locking: Shared/exclusive file locking for coordination

  • Chunked Upload: Handle files larger than 64KB tool call limit

Related MCP server: Local Files MCP Server

Safety Features

  • No permanent deletion: All deletions go to protected trash with SHA256 verification

  • Atomic writes: Temp file + os.replace() for crash-safe writes

  • Symlink protection: O_NOFOLLOW + lstat() on all path components

  • Path containment: Workspace-root confinement, no traversal

  • Rate limiting: 100 ops/sec per session

  • Size limits: 10MB max file size, 8KB chunk limit for tool calls

Installation

# Install Python dependencies
pip install -r requirements.txt

# Install system dependencies (Ubuntu/Debian)
sudo scripts/install_deps.sh

Usage

# Run the MCP server
python -m mcp_simple_shell.server

# Or use the entry point
mcp-simple-shell

The server runs on streamable-http transport by default.

Tools

File Operations

  • file_read - Read text files (with encoding support)

  • file_read_range - Read specific byte ranges

  • file_write - Create or overwrite files

  • file_overwrite - Replace existing files (trash old version)

  • file_append - Append to files

  • file_rename - Rename files

  • file_delete - Move to trash

  • file_copy - Copy files

  • file_move - Move/rename files

  • file_diff - Unified diff between files

  • file_touch - Create empty file or update mtime

  • file_stat - Get file metadata

Directory Operations

  • make_dir - Create directories

  • delete_dir - Delete directories (with recursive trash)

  • copy_dir - Copy directory trees

  • move_dir - Move directory trees

  • rename_dir - Rename directories

  • list_dir - List directory contents

  • file_list - Recursive listing with filters

Text Processing

  • file_replace_section - Exact string replacement

  • file_patch - Apply unified diff patches

Binary Operations

  • file_read_binary - Read raw bytes (hex + ASCII)

  • file_write_binary - Write raw bytes at offset

  • file_hexdump - Formatted hex dump

  • file_find_bytes - Pattern search with wildcards

  • file_diff_binary - Byte-by-byte comparison

Advanced Processing

  • file_unpack - UPX unpacking

  • file_decrypt - XOR/AES-CBC decryption

  • file_extract_range - Extract byte ranges

  • file_yara_scan - YARA rule scanning

  • file_magic - File type detection (libmagic)

  • file_carve_firmware - Firmware extraction (binwalk)

  • file_find_embedded - Entropy-based embedded file detection

  • file_split_segments - ELF/PE segment splitting

SQLite

  • sqlite_create_file - Create database

  • sqlite_open_file - Open database (read-only option)

  • sqlite_get_catalog - Full schema catalog

  • sqlite_execute - Execute SQL

  • sqlite_close - Close connection

  • sqlite_table_info - Table column info

System

  • file_hash - SHA256/MD5/SHA1/SSDEEP/TLSH

  • file_rebase - PE image base change

  • disk_usage - Workspace statistics

  • server_info - Server configuration

Trash

  • list_trash - List trashed files

  • trash_info - View trash metadata

  • restore_from_trash - Restore with SHA256 verification

Locking

  • file_lock - Acquire advisory lock

  • file_unlock - Release advisory lock

Chunked Upload

  • begin_upload - Start upload session

  • append_chunk - Append chunk

  • finish_upload - Finalize upload

  • cancel_upload - Cancel upload

Configuration

Workspace root: ./workspace (created automatically) Trash directory: ./workspace/.trash (managed only by trash tools)

Requirements

  • Python 3.10+

  • Linux (primary), macOS (limited binary tool support)

  • System packages: upx, binwalk, yara, libyara-dev, file, python3-dev, build-essential, libfuzzy-dev

License

MIT

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables file system operations such as listing, reading, and creating files within a scoped local project directory. It provides a secure way to manage local files through standardized MCP tools built with FastMCP.
      -
    • F
      license
      A
      quality
      C
      maintenance
      Enables saving and managing files in a sandboxed local folder via MCP, with tools for listing, reading, writing, appending, searching, moving, and deleting files and directories.
      10
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables ChatGPT or any MCP client to operate safely on a designated workspace by listing, reading, searching, writing, and trashing files, inspecting Git status/log/diff, and optionally running allowlisted executables without a shell.
      Apache 2.0