🚀 Add secure shell command execution capabilities to your AI applications with the Shell MCP Server! Built for the Model Context Protocol.
- 🔒 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
# Using pip pip install shell-mcp-server # Using uv (recommended) uv pip install shell-mcp-serverAdd this to your Claude Desktop config to enable shell command execution:
📝 Click to view configuration
{ "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" ] } } }# 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" )# 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" )# 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" )# 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" )# 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" )Configure behavior with command-line arguments:
| Argument | Description |
|---|---|
directories | 📁 List of allowed directories |
--shell name path | 🐚 Shell specifications (name and path) |
Environment variables:
COMMAND_TIMEOUT: ⏱️ Max execution time in seconds (default: 30)
- 🔐 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
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_serverContributions are welcome! Feel free to:
- 🐛 Report bugs
- 💡 Suggest features
- 🔧 Submit pull requests
- 📚 Improve documentation
MIT License - see LICENSE for details.
Built for the Model Context Protocol | Made with ❤️ by the MCP Community
🎉 Star us on GitHub!
If you find this tool useful, consider giving it a star! It helps others discover the project.