🖥️ 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:
📝 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"
]
}
}
}
🎮 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 |
|---|---|
directories | 📁 List of allowed directories |
--shell name path | 🐚 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
🎉 Star us on GitHub!
If you find this tool useful, consider giving it a star! It helps others discover the project.