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

# Clone the repository
git clone https://github.com/yourusername/mcp-shelljs.git
cd mcp-shelljs

# Install dependencies
npm install

# Build the project
npm run build

Usage

Command Line

# Default mode (read-only)
node dist/index.js

# Enable read-write operations
node dist/index.js --enable-rw

# Enable exec command (careful!)
node dist/index.js --enable-exec

# Enable both
node dist/index.js --enable-rw --enable-exec

TypeScript Integration

// Import and initialize the MCP server
import { startMCPServer } from 'mcp-shelljs';

// Start the server with default configuration (read-only)
startMCPServer();

// Or with custom security configuration
startMCPServer({
  enableRw: true,   // Enable read-write operations
  enableExec: false // Keep exec disabled
});

Security Design

MCP-ShellJS implements a simple security model:

1. Read-Only Mode (Default): Only commands that don't modify the filesystem are available
2. Read-Write Mode (--enable-rw): Enables commands that can create, modify, or delete files
3. Exec Mode (--enable-exec): Enables the potentially dangerous exec 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 and find 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

directory://{path}?include={glob}&exclude={glob}&honor_gitignore={boolean}

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:

directory:///project/src?include=*.ts&exclude=*.test.ts&honor_gitignore=true

File Resource

file://{path}?lines={boolean}&start={number}&end={number}

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:

file:///project/src/index.ts?lines=true&start=10&end=50

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

GPL-3.0-or-later