Blazickjp Shell MCP Server

🚀 🖥️ Shell MCP Server

Enhance your AI applications with secure Shell command execution using the Shell MCP Server! Built specifically for the Model Context Protocol.

🚀 Quick Start

Installation

# Using pip
pip install shell-mcp-server

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

🔌 Claude Desktop Integration

Add the following content to your Claude Desktop configuration to enable Shell command execution:

{
    "mcpServers": {
        "shell-mcp-server": {
            "command": "uv",
            "args": [
                "--venv",
                ".venv",
                "python",
                "-m",
                "shell_mcp_server.server",
                "--port",
                "23456"
            ]
        }
    }
}

✨ Features

• 🔒 Secure Execution - Commands run only in the specified directory.
• 🐚 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 First - Built-in directory and Shell validation.

💻 Usage Examples

Basic Usage

# Start the server
uv python -m shell_mcp_server.server --port 23456

# Send a command
curl http://localhost:23456/shell -X POST -d "echo Hello World!"

Advanced Usage

from shell_mcp_server import ShellMCPClient

client = ShellMCPClient("http://localhost:23456")
# Execute a command and get the output
result = client.run_command("ls -a")
print(result.stdout)  # Print the output

Configuration

Configure the server as follows:

# Specify the configuration file when starting
uv python -m shell_mcp_server.server --config config.json

Example of config.json:

{
    "port": 23456,
    "allowed_commands": ["ls", "echo"],
    "super_users": ["user1", "user2"]
}

Security Features

• Command Whitelist - Only allow specified commands to execute.
• Super User Support - Allow specific users to bypass command restrictions.
• Access Control - Restrict connections by IP or other means.

Development

Set up the 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

# Run tests with coverage
python -m pytest --cov=shell_mcp_server

Contribution

Contributions are welcome! Feel free to:

• 🐛 Report issues
• 💡 Suggest improvements
• 🔧 Submit pull requests
• 📚 Improve documentation

📄 License

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