Shell MCP Server

🚀 Shell MCP Server

A service implementing the Model Context Protocol (MCP) based on Node.js, offering secure shell command execution. This server enables AI models to execute shell commands in a controlled environment, with built - in security measures. It can be easily integrated with Claude Desktop to connect Claude with your shell.

🚀 Quick Start

Run npx mcp-shell.

To add it to Claude Desktop, run npx mcp-shell config. Alternatively, manually add npx -y mcp-shell to the configuration.

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

✨ Features

• MCP - compatible server implementation
• Secure command execution with blacklist protection
• Command existence verification
• Standard input/output (I/O) transmission
• Error handling and graceful shutdown

📦 Installation

Run npx mcp-shell.

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

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

🔒 Security Features

The server implements the following security measures:

1. Command Blacklist Protection

   • Blocks the execution of dangerous system commands.
   • Prevents access to critical system modifications.
   • Protects the file system from damage.
   • Prevents privilege escalation attacks.

2. Command Verification

   • Verifies the existence of commands before execution.
   • Checks against the blacklist.
   • Returns clear error messages for invalid commands.

💻 Usage Examples

run_command

Execute a shell command and return its output.

Input Format:

{
  "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 reasons:

• File system destruction commands (rm, rmdir, del)
• Disk/file system 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 when receiving the SIGINT signal

🔧 Technical Details

The server is built using the following technologies:

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

🛠️ Development Instructions

To modify the security settings, you can do the following:

1. Edit the BLACKLISTED_COMMANDS collection to adjust the blocked commands.
2. Modify the validateCommand function to add additional verification rules.
3. Improve the command parsing logic in the CallToolRequestSchema processor.