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:

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 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

Integrations