A
licenseA
qualityA
maintenanceA 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.
1
201
MIT
MCP Shell Server
by fastmcp-me
Allows secure execution of whitelisted shell commands with support for stdin input, returning stdout, stderr, exit status, and execution time.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Shell Server list the files in my project directory"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: Shell-MCP
MCP client setting in your Claude.app
Published version
code ~/Library/Application\ Support/Claude/claude_desktop_config.json{
"mcpServers": {
"shell": {
"command": "uvx",
"args": [
"mcp-shell-server"
],
"env": {
"ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"
}
},
}
}Local version
Configuration
code ~/Library/Application\ Support/Claude/claude_desktop_config.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:
npx -y @smithery/cli install mcp-shell-server --client claudeManual Installation
Installing via Smithery
To install Shell Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install mcp-shell-server --client claudeManual Installation
pip install mcp-shell-serverInstalling via Smithery
To install Shell Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install mcp-shell-server --client claudeUsage
Starting the Server
ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server
# Or using the alias
ALLOWED_COMMANDS="ls,cat,echo" uvx mcp-shell-serverThe 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:
ALLOW_COMMANDS="ls,cat,echo" # Basic format
ALLOWED_COMMANDS="ls ,echo, cat" # With spaces (using alias)
ALLOW_COMMANDS="ls, cat , echo" # Multiple spacesRequest Format
# 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:
{
"stdout": "command output",
"stderr": "",
"status": 0,
"execution_time": 0.123
}Error response:
{
"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
git clone https://github.com/yourusername/mcp-shell-server.git
cd mcp-shell-serverInstall dependencies including test requirements
pip install -e ".[test]"Running Tests
pytestAPI 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
Available Tools
1 toolshell_executeC
Execute a shell command Allowed commands: echo, cat, ls Allowed patterns:
Inputs: command (required), directory (required), stdin, timeout.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
B3/5.0
Scored across 1 tool
Disambiguation5/5
There is only one tool, so there is no possibility of confusion. The tool's purpose is clearly defined as executing shell commands with specific allowed commands.
Naming Consistency5/5
With a single tool, naming consistency is trivially maintained. The name 'shell_execute' follows a predictable pattern and clearly conveys its function.
Tool Count3/5
The single tool is borderline for a server named 'MCP Shell Server'. While the restricted command set makes it coherent, a full shell server would typically require more tools to handle different operations.
Completeness2/5
The tool only supports echo, cat, and ls, which is a very limited subset of shell capabilities. Missing common operations like file manipulation, process control, or piping leaves significant gaps for a tool claiming to be a shell server.
Maintenance
ActivityInactive
ResponsivenessOutdated data
Related MCP Connectors
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
I run shell commands on your private cloud environment (bash, sh, zsh)
Paid remote MCP for LLM security scans, jailbreak checks, analytics, checkout, and readiness.
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Related MCP Servers
- AlicenseBqualityDmaintenanceA secure MCP server for executing whitelisted shell commands with resource and timeout controls, designed for integration with Claude and other MCP-compatible LLMs.20389 npm7MIT
- AlicenseNot gradedqualityDmaintenanceEnables secure execution of shell commands via MCP with multiple security layers including command whitelisting and directory restrictions.586 npmMIT
- AlicenseBqualityDmaintenanceProvides a secure MCP interface to execute commands inside Docker Compose service containers, with real-time output capture and configurable timeouts.1306 npmMIT