A
securityA
licenseA
qualityA secure server for executing terminal commands within predefined paths, allowing safe interaction by Large Language Models with operating system environments.
Last updated -
1
75
10
MIT License
The Shell MCP Server enables AI applications to securely execute shell commands across Unix and Windows systems. It provides secure command execution restricted to pre-approved directories with built-in validation to prevent directory traversal attacks. The server supports multiple shells (bash, sh, cmd, powershell) and includes timeout control to automatically terminate long-running commands. Key capabilities include basic file operations (listing directories, finding files, content manipulation), project management (Git operations, package management), system monitoring (resource usage, process details), and general command execution with the same permissions as the server process for security isolation.
Allows execution of git commands for repository management, including viewing repository status and differences between commits.
Enables secure execution of shell commands in specified directories with support for multiple shell types, timeout control, and built-in security features to safely run system commands for file operations, git commands, package management, and system monitoring.
🖥️ Shell MCP Server
🚀 Add secure shell command execution capabilities to your AI applications with the Shell MCP Server! Built for the Model Context Protocol.
✨ Features
🔒 Secure Execution - Commands run only in specified directories
🐚 Multiple Shells - Support for bash, sh, cmd, powershell
⏱️ Timeout Control - Automatic termination of long-running commands
🌍 Cross-Platform - Works on both Unix and Windows systems
🛡️ Safe by Default - Built-in directory and shell validation
🚀 Quick Start
Installation
# Using pip
pip install shell-mcp-server
# Using uv (recommended)
uv pip install shell-mcp-server
🔌 Claude Desktop Integration
Add this to your Claude Desktop config to enable shell command execution:
{
"mcpServers": {
"shell-mcp-server": {
"command": "uv",
"args": [
"--directory",
"/path/to/shell-mcp-server",
"run",
"shell-mcp-server",
"/path/to/allowed/dir1",
"/path/to/allowed/dir2",
"--shell", "bash", "/bin/bash",
"--shell", "zsh", "/bin/zsh"
]
}
}
}
🎮 Usage Examples
Basic File Operations
# List directory contents
result = execute_command(
command="ls -la",
shell="bash",
cwd="/path/to/project"
)
# Find files by pattern
result = execute_command(
command="find . -name '*.py'",
shell="bash",
cwd="/path/to/project"
)
Project Management
# Git operations
result = execute_command(
command="git status && git diff",
shell="bash",
cwd="/path/to/repo"
)
# Package management
result = execute_command(
command="pip list --outdated",
shell="bash",
cwd="/path/to/python/project"
)
System Information
# Resource usage
result = execute_command(
command="df -h && free -h",
shell="bash",
cwd="/path/to/dir"
)
# Process monitoring
result = execute_command(
command="ps aux | grep python",
shell="bash",
cwd="/path/to/dir"
)
File Processing
# Search file content
result = execute_command(
command="grep -r 'TODO' .",
shell="bash",
cwd="/path/to/project"
)
# File manipulation
result = execute_command(
command="awk '{print $1}' data.csv | sort | uniq -c",
shell="bash",
cwd="/path/to/data"
)
Windows-Specific Examples
# List processes
result = execute_command(
command="Get-Process | Where-Object {$_.CPU -gt 10}",
shell="powershell",
cwd="C:\\path\\to\\dir"
)
# System information
result = execute_command(
command="systeminfo | findstr /B /C:'OS'",
shell="cmd",
cwd="C:\\path\\to\\dir"
)
⚙️ Configuration
Configure behavior with command-line arguments:
Argument | Description |
| 📁 List of allowed directories |
| 🐚 Shell specifications (name and path) |
Environment variables:
COMMAND_TIMEOUT: ⏱️ Max execution time in seconds (default: 30)
🛡️ Security Features
🔐 Directory Isolation: Commands can only execute in specified directories
🔒 Shell Control: Only configured shells are allowed
⏰ Timeout Protection: All commands have a configurable timeout
🛑 Path Validation: Working directory validation prevents traversal attacks
👤 Permission Isolation: Commands run with the same permissions as the server process
🛠️ Development
Set up your development environment:
# Create and activate virtual environment
uv venv
source .venv/bin/activate
# Install development dependencies
uv pip install -e ".[test]"
# Run tests
python -m pytest
# Run tests with coverage
python -m pytest --cov=shell_mcp_server
🤝 Contributing
Contributions are welcome! Feel free to:
🐛 Report bugs
💡 Suggest features
🔧 Submit pull requests
📚 Improve documentation
📜 License
MIT License - see LICENSE for details.
🌟 Enhance Your AI with Secure Shell Access! 🌟
Built for the Model Context Protocol | Made with ❤️ by the MCP Community
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
A secure server that enables AI applications to execute shell commands in specified directories, supporting multiple shell types (bash, sh, cmd, powershell) with built-in security features like directory isolation and timeout control.
- ✨ Features
- 🚀 Quick Start
- 🎮 Usage Examples
- ⚙️ Configuration
- 🛡️ Security Features
- 🛠️ Development
- 🤝 Contributing
- 📜 License
Related Resources
Related MCP Servers
- -securityFlicense-qualityA robust SSH server facilitating secure remote command execution with TMUX session management, multi-window support, and smart session recovery for improved AI-human interaction.Last updated -4
- -securityAlicense-qualityA lightweight FastAPI server that allows remote execution of shell commands on Windows, with real-time output streaming and security features like API key authentication and rate limiting.Last updated -1MIT License
- -securityFlicense-qualityEnables AI assistants to securely execute shell commands on local machines through an SSH interface with session management, command execution, and sudo support.Last updated -