home / mcp / shell mcp server

Shell MCP Server

Execute a secure shell in Claude Desktop using the Model Context Protocol.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "hdresearch-mcp-shell": {
      "command": "npx",
      "args": [
        "mcp-shell"
      ]
    }
  }
}

Shell MCP Server provides a secure, Node.js based MCP implementation that enables controlled shell command execution. It is designed to be easily integrated with Claude Desktop, allowing you to run shell commands from AI models while enforcing strict security and input validation to protect your system.

How to use

You connect to the Shell MCP Server from an MCP client by starting the local server process and using the MCP transport to send commands. The server validates each command, executes it in a restricted environment, and returns the resulting output or an error message. Use this to enable AI-driven shell interactions that stay within safe boundaries.

How to install

Prerequisites: ensure you have Node.js and npm installed on your system. You can verify by running node -v and npm -v in your terminal.

Install and run the MCP shell server locally using the following command.

npx mcp-shell

To configure the MCP tool for Claude Desktop, use the following command to generate or update the config.

npx mcp-shell config

If you are updating your Claude Desktop configuration manually, you can add the MCP command to your profile by including the local MCP start command in your setup as shown above.

Security and operation notes

The server includes several security measures to protect your system while enabling shell command execution. It implements a command blacklist to block dangerous operations, validates that a command exists before attempting execution, and provides clear error messages when commands fail or are disallowed. The transport uses standard I/O to communicate between the MCP client and server.

Key security features include: a blacklist protecting against file system destruction, privilege escalation, and other high-risk actions; command existence validation to prevent executing non-existent or unexpected commands; and explicit error reporting for invalid or disallowed requests.

Error handling

The server handles common errors such as command-not-found, blacklist violations, execution failures, and MCP protocol errors. It also supports graceful shutdown on receiving an interrupt signal, ensuring the system remains stable during server stop or restart.

Implementation details

The Shell MCP Server is built with the Model Context Protocol SDK and uses a StdioServerTransport for communication. It relies on execa for executing shell commands and command-exists for validating command availability.

Development

If you want to adjust security behavior, you can update the BLACKLISTED_COMMANDS set, modify the validateCommand function to add further checks, or enhance the CallToolRequestSchema handling to support additional parsing rules.

Available tools

run_command

Executes a shell command and returns its output, handling input, output, and errors through the MCP transport.