Shell MCP Server

local-only server

The server can only run on the client’s local machine because it depends on local resources.

Integrations

  • Implemented as a Node.js application that follows the Model Context Protocol, offering command validation and secure shell command execution.

  • Provides secure execution of shell commands with protective measures against dangerous operations including file system destruction, permission changes, and privilege escalation.

Shell MCP Server

A Node.js implementation of the Model Context Protocol (MCP) that provides secure shell command execution capabilities. This server allows AI models to execute shell commands in a controlled environment with built-in security measures. Easily integrates with Claude Desktop for connecting Claude with your shell.

Features

  • MCP-compliant server implementation
  • Secure command execution with blacklist protection
  • Command existence validation
  • Standard I/O based transport
  • Error handling and graceful shutdown

Installation

Run npx mcp-shell.

To add it to Claude Desktop, run npx mcp-shell config. Or add npx -y mcp-shell to your config manually.

Start (or restart) Claude Desktop and you should see the MCP tool listed on the landing page.

Security Features

The server implements several security measures:

  1. Command Blacklisting
    • Prevents execution of dangerous system commands
    • Blocks access to critical system modifications
    • Protects against file system destruction
    • Prevents privilege escalation
  2. Command Validation
    • Verifies command existence before execution
    • Validates against the blacklist
    • Returns clear error messages for invalid commands

Available Tools

The server provides one tool:

run_command

Executes a shell command and returns its output.

Input Schema:

{ "type": "object", "properties": { "command": { "type": "string" } } }

Response:

  • Success: Command output as plain text
  • Error: Error message as plain text

Blacklisted Commands

The following command categories are blocked for security:

  • File System Destruction Commands (rm, rmdir, del)
  • Disk/Filesystem Commands (format, mkfs, dd)
  • Permission/Ownership Commands (chmod, chown)
  • Privilege Escalation Commands (sudo, su)
  • Code Execution Commands (exec, eval)
  • System Communication Commands (write, wall)
  • System Control Commands (shutdown, reboot, init)

Error Handling

The server includes comprehensive error handling:

  • Command not found errors
  • Blacklisted command errors
  • Execution errors
  • MCP protocol errors
  • Graceful shutdown on SIGINT

Implementation Details

The server is built using:

  • Model Context Protocol SDK
  • StdioServerTransport for communication
  • execa for command execution
  • command-exists for command validation

Development

To modify the security settings, you can:

  1. Edit the BLACKLISTED_COMMANDS set to adjust blocked commands
  2. Modify the validateCommand function to add additional validation rules
  3. Enhance the command parsing logic in the CallToolRequestSchema handler

You must be authenticated.

A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

A Node.js implementation of the Model Context Protocol that provides secure shell command execution capabilities, allowing AI models like Claude to run shell commands in a controlled environment with built-in security measures.

  1. Features
    1. Installation
      1. Security Features
        1. Available Tools
          1. run_command
          2. Blacklisted Commands
            1. Error Handling
              1. Implementation Details
                1. Development