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 dangerousexec
command 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
grep
andfind
across codebases - Text processing: Transform files with
sed
without 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
- AsecurityAlicenseAqualityA 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 5 months ago204754TypeScriptMIT License
- AsecurityAlicenseAqualityAn MCP server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface for LLMs.Last updated 2 months ago1070PythonMIT 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 22 days ago10PythonApache 2.0
- AsecurityAlicenseAqualityAn 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 23 days ago93466JavaScriptMIT License