Skip to main content
Glama

Shell MCP Server

by hdresearch

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

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

local-only server

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

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

                Related MCP Servers

                • A
                  security
                  F
                  license
                  A
                  quality
                  A Model Context Protocol server implementation that enables secure remote command execution via SSH, with features for managing and using SSH credentials.
                  Last updated -
                  5
                  0
                  9
                • -
                  security
                  F
                  license
                  -
                  quality
                  A TypeScript application that allows Claude to safely execute bash commands with security safeguards, providing a secure interface through the Model Context Protocol.
                • A
                  security
                  A
                  license
                  A
                  quality
                  A secure Model Context Protocol server that allows AI models to safely interact with Windows command-line functionality, enabling controlled execution of system commands, project creation, and system information retrieval.
                  Last updated -
                  8
                  7
                  MIT License
                • -
                  security
                  F
                  license
                  -
                  quality
                  A secure interface that enables language models to execute shell commands on the host operating system through the Model Context Protocol.
                  Last updated -
                  1

                View all related MCP servers

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/hdresearch/mcp-shell'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server