Skip to main content
Glama

MCP-ShellJS

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:

ParameterDescription
includeGlob pattern(s) to include (e.g., *.js,*.ts)
excludeGlob pattern(s) to exclude (e.g., node_modules,dist)
honor_gitignoreWhen true, filters out files matching patterns in .gitignore
recursiveWhen 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:

ParameterDescription
linesWhen true, includes line numbers in output
startFirst line to include (1-based indexing)
endLast line to include
highlightGlob 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

ToolDescriptionArguments
catOutput file contentsfiles: String/Array, options: Object with -n (number lines)
grepSearch files for patternsregex, files, options: Object with -v (invert), -l (filenames only), -i (ignore case)
findRecursively find filespaths: String/Array (returns file paths including base dirs)
lsList directory contentspaths: String/Array, options: Object with -R (recursive), -A (all), -L (follow symlinks), -d (dirs only)
whichLocate a commandcommand: String (returns path to command)
pwdPrint working directory(no arguments)
testTest file conditionsexpression: String (e.g., -d path directory exists, -f path file exists)
headShow first linesfiles: String/Array, options: Object with -n <num> (lines to show)
tailShow last linesfiles: String/Array, options: Object with -n <num> (lines to show)
sortSort linesfiles: String/Array, options: Object with -r (reverse), -n (numeric)
uniqFilter duplicated linesinput: String, output: String, options: Object with -i (ignore case), -c (count), -d (duplicates only)

Read-Write Tools

ToolDescriptionArguments
mkdirCreate directoriesdir: String/Array, options: Object with -p (create intermediate dirs)
touchCreate/update filesfiles: String/Array, options: Object with -c (no create), -a (access time only), -m (mod time only)
cpCopy files/directoriessource: String/Array, dest: String, options: Object with -R (recursive), -n (no clobber), -f (force)
mvMove files/directoriessource: String/Array, dest: String, options: Object with -f (force), -n (no clobber)
rmRemove files/directoriesfiles: String/Array, options: Object with -r/-R (recursive), -f (force)
sedStream editor for filessearch_regex: RegExp, replacement: String, files: String/Array, options: Object with -i (in-place)

Special Permission Tools

ToolDescriptionArguments
execExecute commandcommand: String, options: Object with async, silent, requires allowExec: true config

License

GPL-3.0-or-later

-
security - not tested
F
license - not found
-
quality - not tested

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.

  1. Overview
    1. Features
      1. Installation
        1. Usage
          1. Command Line
          2. TypeScript Integration
        2. Security Design
          1. Why Use MCP-ShellJS?
            1. Resources
              1. Directory Resource
              2. File Resource
            2. Tools
              1. Read-Only Tools
              2. Read-Write Tools
              3. Special Permission Tools
            3. License

              Related MCP Servers

              • A
                security
                A
                license
                A
                quality
                A 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 ago
                20
                475
                4
                TypeScript
                MIT License
              • A
                security
                A
                license
                A
                quality
                An MCP server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface for LLMs.
                Last updated 2 months ago
                10
                70
                Python
                MIT License
                • Apple
              • -
                security
                A
                license
                -
                quality
                A 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 ago
                10
                Python
                Apache 2.0
                • Linux
              • A
                security
                A
                license
                A
                quality
                An 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 ago
                9
                346
                6
                JavaScript
                MIT License
                • Linux
                • Apple

              View all related MCP servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/erniebrodeur/mcp-shelljs'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server