🖥️ 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.
Metadata
Release files for shell-mcp-server 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| shell_mcp_server-0.1.0.tar.gz | 24.3 kB | Without provenance | Details for shell_mcp_server-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| shell_mcp_server-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for shell_mcp_server-0.1.0-py3-none-any.whl |
Total release size: 31.1 kB
Release files / shell_mcp_server-0.1.0.tar.gz
| Download URL | shell_mcp_server-0.1.0.tar.gz |
|---|---|
| Size | 24.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
12bfbe43303b84a179898a67fb9703be7a10d6a5e95d7071f26657c102b4ee88
|
|
BLAKE2b-256 checksum How to use checksums |
fa686bc861554db4f8d7bcadb12b0be1c262ee38052363c316601c7e3c3cecfe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.5.4
|
Release files / shell_mcp_server-0.1.0-py3-none-any.whl
| Download URL | shell_mcp_server-0.1.0-py3-none-any.whl |
|---|---|
| Size | 6.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b2e784c804a1e5210625d3e8e3e88b229e4be2cb26380c6a4136d463f792ca21
|
|
BLAKE2b-256 checksum How to use checksums |
9fc7222b8ffd7cfb2b39b95981bb3cfa3287b52bab7979687ba6aad55616b076
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.5.4
|
Security for shell-mcp-server 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.