MCP-ShellJS is a secure bridge between Model Context Protocol (MCP) and ShellJS, enabling LLMs to execute shell commands in a controlled environment.

What are the main features of MCP-ShellJS?

Key features include simplified security with read-only mode by default, optional read-write and exec permissions, schema-based validation, full ShellJS functionality, TypeScript implementation, and a simple API for LLM integration.

How do I install MCP-ShellJS?

Install MCP-ShellJS by cloning the repository, installing dependencies, and building the project using npm commands.

What security measures does MCP-ShellJS implement?

MCP-ShellJS implements security through read-only mode, optional read-write mode, and controlled exec command permissions. It also uses schema-based validation.

Why should I use MCP-ShellJS?

Use MCP-ShellJS for efficient exploration, text processing, safe automation, and powerful pipelines with controlled risk for AI developers.

What is the directory resource in MCP-ShellJS?

The directory resource provides directory listing with filtering capabilities using include, exclude, and honor_gitignore parameters.

What are the read-only tools available in MCP-ShellJS?

Read-only tools include cat, grep, find, ls, which, pwd, test, head, tail, sort, and uniq.

What are the read-write tools available in MCP-ShellJS?

Read-write tools include mkdir, touch, cp, mv, rm, and sed.

What is the special permission tool in MCP-ShellJS?

The special permission tool is exec, which requires explicit `allowExec: true` configuration for use.

MCP-ShellJS

Q: What is the file resource in MCP-ShellJS?

The file resource provides file contents with options for viewing specific portions using lines, start, and end parameters.

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)