A
securityA
licenseA
qualityA secure MCP server for executing whitelisted shell commands with resource and timeout controls, designed for integration with Claude and other MCP-compatible LLMs.
Last updated -
20
143
2
TypeScript
MIT License
Provides controlled access to ShellJS commands for filesystem operations, including read-only functions (ls, grep, find) and optional read-write capabilities (mkdir, touch, cp, mv, rm, sed).
Built with TypeScript for strong typing, enabling integration with TypeScript applications through a programmatic API.
Implements schema-based validation for command inputs and responses, ensuring that all operations conform to defined security constraints.
MCP-ShellJS
An MCP server that provides safe, controlled ShellJS access for LLMs like Claude.
Overview
MCP-ShellJS bridges the Model Context Protocol (MCP) with ShellJS, enabling AI systems to execute shell commands within a secure sandbox. It provides controlled filesystem access with multiple security layers.
Features
- Simplified security:
- Read-only mode by default
- Optional read-write mode via command line flag
- Optional exec permission via command line flag
- Schema-based validation with Zod
- Full ShellJS functionality (
ls,grep,sed,find, etc.) - TypeScript implementation with strong typing
- Simple API for LLM integration
Installation
Usage
Command Line
TypeScript Integration
Security Design
MCP-ShellJS implements a simple security model:
- Read-Only Mode (Default): Only commands that don't modify the filesystem are available
- Read-Write Mode (
--enable-rw): Enables commands that can create, modify, or delete files - Exec Mode (
--enable-exec): Enables the potentially dangerousexeccommand for executing arbitrary shell commands
The server runs with stdio transport only, making it suitable for integration with desktop LLM applications.
Why Use MCP-ShellJS?
For AI developers, MCP-ShellJS enables powerful filesystem capabilities with controlled risk:
- Efficient exploration: Fast search with
grepandfindacross codebases - Text processing: Transform files with
sedwithout loading them entirely - Safe automation: Let AI help with file organization and management
- Powerful pipelines: Chain operations with Unix-style piping
Resources
Directory Resource
Provides directory listing with powerful filtering capabilities:
| Parameter | Description |
|---|---|
include | Glob pattern(s) to include (e.g., *.js,*.ts) |
exclude | Glob pattern(s) to exclude (e.g., node_modules,dist) |
honor_gitignore | When true, filters out files matching patterns in .gitignore |
recursive | When true, includes subdirectories recursively |
Example:
File Resource
Provides file contents with options for viewing specific portions:
| Parameter | Description |
|---|---|
lines | When true, includes line numbers in output |
start | First line to include (1-based indexing) |
end | Last line to include |
highlight | Glob pattern to highlight matching text |
Example:
Tools
MCP-ShellJS exposes ShellJS commands as tools, grouped by security risk level:
Read-Only Tools
| Tool | Description | Arguments |
|---|---|---|
cat | Output file contents | files: String/Array, options: Object with -n (number lines) |
grep | Search files for patterns | regex, files, options: Object with -v (invert), -l (filenames only), -i (ignore case) |
find | Recursively find files | paths: String/Array (returns file paths including base dirs) |
ls | List directory contents | paths: String/Array, options: Object with -R (recursive), -A (all), -L (follow symlinks), -d (dirs only) |
which | Locate a command | command: String (returns path to command) |
pwd | Print working directory | (no arguments) |
test | Test file conditions | expression: String (e.g., -d path directory exists, -f path file exists) |
head | Show first lines | files: String/Array, options: Object with -n <num> (lines to show) |
tail | Show last lines | files: String/Array, options: Object with -n <num> (lines to show) |
sort | Sort lines | files: String/Array, options: Object with -r (reverse), -n (numeric) |
uniq | Filter duplicated lines | input: String, output: String, options: Object with -i (ignore case), -c (count), -d (duplicates only) |
Read-Write Tools
| Tool | Description | Arguments |
|---|---|---|
mkdir | Create directories | dir: String/Array, options: Object with -p (create intermediate dirs) |
touch | Create/update files | files: String/Array, options: Object with -c (no create), -a (access time only), -m (mod time only) |
cp | Copy files/directories | source: String/Array, dest: String, options: Object with -R (recursive), -n (no clobber), -f (force) |
mv | Move files/directories | source: String/Array, dest: String, options: Object with -f (force), -n (no clobber) |
rm | Remove files/directories | files: String/Array, options: Object with -r/-R (recursive), -f (force) |
sed | Stream editor for files | search_regex: RegExp, replacement: String, files: String/Array, options: Object with -i (in-place) |
Special Permission Tools
| Tool | Description | Arguments |
|---|---|---|
exec | Execute command | command: String, options: Object with async, silent, requires allowExec: true config |
License
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A secure MCP server that provides controlled ShellJS access for LLMs, enabling AI systems to safely execute shell commands and interact with the filesystem within a configurable security sandbox.
Related MCP Servers
- AsecurityAlicenseAqualityAn MCP server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface for LLMs.Last updated -1058PythonMIT License
- -securityAlicense-qualityA secure, container-based implementation of the Model Context Protocol (MCP) that provides sandboxed environments for AI systems to safely execute code, run commands, access files, and perform web operations.Last updated -9PythonApache 2.0
- -securityAlicense-qualityAn MCP server that enables secure execution of shell commands across Windows, macOS, and Linux with built-in whitelisting and approval mechanisms for enhanced security.Last updated -606JavaScriptMIT License