Shell MCP Server

🚀 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.
• 🐚 Multi-Shell Support - Supports bash, sh, cmd, and powershell.
• ⏱️ Timeout Control - Automatically terminates long-running commands.
• 🌍 Cross-Platform - Works on both Unix and Windows systems.
• 🛡️ Security by Default - Built-in directory and shell program verification.

🚀 Quick Start

Installation

# Using pip
pip install shell-mcp-server

# Using uv (Recommended)
uv pip install shell-mcp-server

🔌 Claude Desktop Integration

Add this content to your Claude desktop configuration to enable Shell command execution:

{
    "mcp": {
        "servers": [
            {
                "name": "shell_mcp",
                "class_name": "ShellMCPClient",
                "args": {}
            }
        ]
    }
}

echo '[mcp]\n  servers = [{{name=\"shell_mcp\", class_name=\"ShellMCPClient\", args={}}}]' >> claudia.toml

💻 Usage Examples

Basic Usage

from shell_mcp_server import ShellMCPClient

# Create a ShellMCP client instance
client = ShellMCPClient()

# Execute a command
response = client.execute("echo Hello, World!")
print(response)  # Output: "Hello, World!\n"

# Set a timeout (optional)
client.timeout = 10  # Set to 10 seconds

# Command with parameters
response = client.execute("ls -l", working_dir="/path/to/dir")
print(response)

Advanced Usage

You can customize the following settings:

• timeout: Specify the timeout (default: unlimited).
• shell_path: Customize the Shell interpreter path (default: /bin/sh).
• env: Customize environment variables.
• working_dir: Set the working directory.

🔧 Development

Set up your development environment:

# Create and activate a virtual environment
uv venv
source .venv/bin/activate

# Install development dependencies
uv pip install -e ".[test]"

# Run tests
python -m pytest

# Tests with coverage
python -m pytest --cov=shell_mcp_server

🤝 Contribution

Contributions are welcome! Feel free to:

• 🐛 Report bugs.
• 💡 Suggest features.
• 🔧 Submit pull requests.
• 📚 Improve documentation.

📄 License

This project is under the MIT License - see LICENSE for details.