MCP Shell Server

A secure, configurable shell command execution server implementing the Model Context Protocol.

View on GitHub

153

Stars

Forks

153

Watchers

Issues

MCP Shell Server provides secure remote execution of whitelisted shell commands via the Model Context Protocol (MCP). It supports standard input, command output retrieval, and enforces strict safety checks on command operations. The tool allows configuration of allowed commands and execution timeouts, and can be integrated with platforms such as Claude.app and Smithery. With robust security assessments and flexible deployment methods, it facilitates controlled shell access for AI agents.

Key Features

Executes only whitelisted shell commands securely

Supports passing standard input (stdin) to commands

Returns command stdout, stderr, exit status, and execution time

Validates commands using safety checks for shell operators

Configurable allowed commands via environment variables

Timeout control for individual command executions

Multiple installation methods (pip, Smithery CLI)

Integration ready for Claude.app and other MCP clients

Security assessment badges and validation

Support for specifying working directories for command execution

Use Cases

Enabling secure shell access for AI assistants

Automating remote command execution with context awareness

Building safe shell endpoints for workflow automations

Integrating controlled shell operations into AI model workflows

Providing model-controlled command-line interface for remote servers

Restricting available shell commands for safety in collaborative tools

Monitoring and retrieving outputs from automated command tasks

Testing context-driven shell command execution in controlled environments

Offering secure backend command execution for chatbots

Facilitating protocol-based shell interactions in cloud or desktop environments

README

MCP Shell Server

A secure shell command execution server implementing the Model Context Protocol (MCP). This server allows remote execution of whitelisted shell commands with support for stdin input.

Features

Secure Command Execution: Only whitelisted commands can be executed
Standard Input Support: Pass input to commands via stdin
Comprehensive Output: Returns stdout, stderr, exit status, and execution time
Shell Operator Safety: Validates commands after shell operators (; , &&, ||, |)
Timeout Control: Set maximum execution time for commands

MCP client setting in your Claude.app

Published version

shell

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

json

{
  "mcpServers": {
    "shell": {
      "command": "uvx",
      "args": [
        "mcp-shell-server"
      ],
      "env": {
        "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"
      }
    },
  }
}

Local version

Configuration

shell

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

json

{
  "mcpServers": {
    "shell": {
      "command": "uv",
      "args": [
        "--directory",
        ".",
        "run",
        "mcp-shell-server"
      ],
      "env": {
        "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"
      }
    },
  }
}

Installation

Installing via Smithery

To install Shell Server for Claude Desktop automatically via Smithery:

bash

npx -y @smithery/cli install mcp-shell-server --client claude

Manual Installation

Installing via Smithery

To install Shell Server for Claude Desktop automatically via Smithery:

bash

npx -y @smithery/cli install mcp-shell-server --client claude

Manual Installation

bash

pip install mcp-shell-server

Installing via Smithery

To install Shell Server for Claude Desktop automatically via Smithery:

bash

npx -y @smithery/cli install mcp-shell-server --client claude

Usage

Starting the Server

bash

ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server
# Or using the alias
ALLOWED_COMMANDS="ls,cat,echo" uvx mcp-shell-server

The ALLOW_COMMANDS (or its alias ALLOWED_COMMANDS ) environment variable specifies which commands are allowed to be executed. Commands can be separated by commas with optional spaces around them.

Valid formats for ALLOW_COMMANDS or ALLOWED_COMMANDS:

bash

ALLOW_COMMANDS="ls,cat,echo"          # Basic format
ALLOWED_COMMANDS="ls ,echo, cat"      # With spaces (using alias)
ALLOW_COMMANDS="ls,  cat  , echo"     # Multiple spaces

Request Format

python

# Basic command execution
{
    "command": ["ls", "-l", "/tmp"]
}

# Command with stdin input
{
    "command": ["cat"],
    "stdin": "Hello, World!"
}

# Command with timeout
{
    "command": ["long-running-process"],
    "timeout": 30  # Maximum execution time in seconds
}

# Command with working directory and timeout
{
    "command": ["grep", "-r", "pattern"],
    "directory": "/path/to/search",
    "timeout": 60
}

Response Format

Successful response:

json

{
    "stdout": "command output",
    "stderr": "",
    "status": 0,
    "execution_time": 0.123
}

Error response:

json

{
    "error": "Command not allowed: rm",
    "status": 1,
    "stdout": "",
    "stderr": "Command not allowed: rm",
    "execution_time": 0
}

Security

The server implements several security measures:

Command Whitelisting: Only explicitly allowed commands can be executed
Shell Operator Validation: Commands after shell operators (;, &&, ||, |) are also validated against the whitelist
No Shell Injection: Commands are executed directly without shell interpretation

Development

Setting up Development Environment

Clone the repository

bash

git clone https://github.com/yourusername/mcp-shell-server.git
cd mcp-shell-server

Install dependencies including test requirements

bash

pip install -e ".[test]"

Running Tests

bash

pytest

API Reference

Request Arguments

Field	Type	Required	Description
command	string[]	Yes	Command and its arguments as array elements
stdin	string	No	Input to be passed to the command
directory	string	No	Working directory for command execution
timeout	integer	No	Maximum execution time in seconds

Response Fields

Field	Type	Description
stdout	string	Standard output from the command
stderr	string	Standard error output from the command
status	integer	Exit status code
execution_time	float	Time taken to execute (in seconds)
error	string	Error message (only present if failed)

Requirements

Python 3.11 or higher
mcp>=1.1.0

License

MIT License - See LICENSE file for details

Star History

Repository Owner

tumf

User

Repository Details

Language Python

Default Branch main

Size 318 KB

Contributors 9

License MIT License

MCP Verified Nov 11, 2025

Programming Languages

Python

98.04%

Shell

1.23%

Makefile

0.42%

Dockerfile

0.32%

Related MCPs

Discover similar Model Context Protocol servers

CMD MCP Server

Execute CMD commands via the Model Context Protocol with cross-platform and SSH support.

CMD MCP Server is an implementation of the Model Context Protocol (MCP) for executing CMD commands on Windows and Linux systems, with additional support for SSH connections. It enables seamless integration of command-line operations with MCP-compatible applications, leveraging the official MCP SDK. Written in TypeScript for cross-platform compatibility, it allows programmatic execution, configuration, and extension of CMD operations through standardized protocols. The server is designed for easy installation, robust configuration, and developer-friendly extension.

⭐ 22
MCP
PhialsBasement/CMD-MCP-Server

mcp-cli

A command-line inspector and client for the Model Context Protocol

mcp-cli is a command-line interface tool designed to interact with Model Context Protocol (MCP) servers. It allows users to run and connect to MCP servers from various sources, inspect available tools, resources, and prompts, and execute commands non-interactively or interactively. The tool supports OAuth for various server types, making integration and automation seamless for developers working with MCP-compliant servers.

⭐ 391
MCP
wong2/mcp-cli

CipherTrust Manager MCP Server

Enables AI assistants to access CipherTrust Manager securely via the Model Context Protocol.

CipherTrust Manager MCP Server provides an implementation of the Model Context Protocol (MCP), offering AI assistants such as Claude and Cursor a unified interface to interact with CipherTrust Manager resources. Communication is facilitated through JSON-RPC over stdin/stdout, enabling key management, CTE client management, user management, and connection management functionalities. The tool is configurable via environment variables and integrates with existing CipherTrust Manager instances using the ksctl CLI for secure resource access.

⭐ 7
MCP
sanyambassi/ciphertrust-manager-mcp-server

AIM Guard MCP

AI-powered security and safety server for Model Context Protocol environments.

AIM Guard MCP is a server implementing the Model Context Protocol (MCP), providing AI-powered security analysis and safety instruction tools tailored for AI agents. It offers features such as contextual security instructions, harmful content detection, API key scanning, and prompt injection detection, all designed to guard and protect interactions with various MCPs and external services. Built for fast integration, it connects with the AIM Intelligence API and is compatible with any MCP-compliant AI assistant.

⭐ 13
MCP
AIM-Intelligence/AIM-MCP

PiloTY

AI Pilot for PTY Operations via the Model Context Protocol

PiloTY is an MCP server that enables AI agents to control interactive terminals as if they were human users. It provides stateful, context-preserving terminal sessions that support interactive programs, SSH connections, and background process management. The system allows secure integration with AI platforms like Claude Code or Claude Desktop to translate natural language instructions into complex terminal workflows. Designed for extensibility and real-world development scenarios, PiloTY empowers agents to manage remote environments, debug interactively, and automate multi-step operations.

⭐ 12
MCP
yiwenlu66/PiloTY

wcgw

Local shell and code agent server with deep AI integration for Model Context Protocol clients.

wcgw is an MCP server that empowers conversational AI models, such as Claude, with robust shell command execution and code editing capabilities on the user's local machine. It offers advanced tools for syntax-aware file editing, interactive shell command handling, and context management to optimize AI-driven workflows. Key protections are included to safeguard files, prevent accidental overwrites, and streamline large file handling, ensuring smooth automated code development and execution.

⭐ 616
MCP
rusiaaman/wcgw

View all Alternatives

Didn't find tool you were looking for?

Search AI Tools

MCP Shell Server

Key Features

Use Cases

README

MCP Shell Server

Features

MCP client setting in your Claude.app

Published version

Local version

Configuration

Installation

Installing via Smithery

Manual Installation

Installing via Smithery

Manual Installation

Installing via Smithery

Usage

Starting the Server

Request Format

Response Format

Security

Development

Setting up Development Environment

Running Tests

API Reference

Request Arguments

Response Fields

Requirements

License

Star History

Repository Owner

Repository Details

Programming Languages

Tags

Related MCPs