mcp shell

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

2. Prevents execution of dangerous system commands

3. Blocks access to critical system modifications
4. Protects against file system destruction

5. Prevents privilege escalation

6. Command Validation

7. Verifies command existence before execution
8. Validates against the blacklist
9. 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