mcp-shell

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