heffrey78/shell-mcp-server

Shell MCP Server

A Model Context Protocol (MCP) server for safe shell command execution. This server allows Claude Desktop to execute shell commands with configurable safety restrictions.

Features

• 🔒 Safe Command Execution: Configurable directory and command restrictions
• ⏱️ Timeout Protection: Prevents long-running commands from hanging
• 📝 Detailed Logging: Comprehensive execution logs and error reporting
• ⚙️ Configurable: Customizable allowed directories and blocked commands
• 🐍 Easy Installation: Standard Python package distribution

Installation

Option 1: Install from PyPI (Recommended)

pip install shell-mcp-server

Option 2: Install from Source

git clone https://github.com/jeffwikstrom/shell-mcp-server.git
cd shell-mcp-server
pip install .

Option 3: Development Install

git clone https://github.com/jeffwikstrom/shell-mcp-server.git
cd shell-mcp-server
pip install -e .

Configuration

Claude Desktop Setup

After installation, add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux/Windows: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "shell-executor": {
      "command": "shell-mcp-server",
      "env": {
        "SHELL_MCP_CONFIG": "/path/to/your/shell_mcp_config.json"
      }
    }
  }
}

Server Configuration (Optional)

Create a configuration file to customize the server behavior:

# Create config file
cp shell_mcp_config.template.json ~/.config/shell_mcp_config.json

Edit the configuration file:

{
  "allowed_directories": [
    "/Users/username",
    "/Users/username/Projects",
    "/Users/username/Documents",
    "/tmp"
  ],
  "blocked_commands": [
    "rm -rf /",
    "sudo rm",
    "sudo shutdown",
    "format",
    "mkfs"
  ],
  "timeout": 30
}

Alternative Configurations

Using Virtual Environment

If you prefer using a virtual environment:

# Create virtual environment
python3 -m venv ~/.local/share/shell-mcp-server
source ~/.local/share/shell-mcp-server/bin/activate
pip install shell-mcp-server

Claude Desktop config:

{
  "mcpServers": {
    "shell-executor": {
      "command": "/Users/username/.local/share/shell-mcp-server/bin/shell-mcp-server"
    }
  }
}

Using pipx (Isolated Installation)

# Install with pipx
pipx install shell-mcp-server

Claude Desktop config:

{
  "mcpServers": {
    "shell-executor": {
      "command": "shell-mcp-server"
    }
  }
}

Using Conda

# Create conda environment
conda create -n shell-mcp python=3.11
conda activate shell-mcp
pip install shell-mcp-server

Claude Desktop config:

{
  "mcpServers": {
    "shell-executor": {
      "command": "/path/to/conda/envs/shell-mcp/bin/shell-mcp-server"
    }
  }
}

Usage

Once configured, you can ask Claude to execute shell commands:

Can you list the files in my Documents directory?
Can you create a new directory called "test-project"?
Can you check the current git status?
Can you run the tests in my project?

Safety Features

Directory Restrictions

By default, commands can only be executed in:

• User home directory and subdirectories
• /tmp and /var/tmp

Command Filtering

The following command patterns are blocked by default:

• rm -rf / (recursive deletion of root)
• sudo rm (privileged deletion)
• sudo shutdown/reboot/halt (system control)
• format, fdisk, mkfs (disk formatting)
• chmod 777 (overly permissive permissions)
• curl | sh, wget | sh (piped execution)

Timeout Protection

Commands are automatically terminated after 30 seconds (configurable).

Configuration Reference

Environment Variables

• SHELL_MCP_CONFIG: Path to configuration file

Configuration File Options

Default Allowed Directories

• $HOME (user home directory)
• $HOME/Documents
• $HOME/Downloads
• $HOME/Desktop
• $HOME/Projects
• $HOME/Development
• /tmp
• /var/tmp
• /~ (fallback for tilde expansion edge cases)

Troubleshooting

Common Issues

1. "Command not found: shell-mcp-server"

   • Ensure the package is installed: pip list | grep shell-mcp-server
   • Check if the installation directory is in your PATH
   • Use full path to executable in Claude config

2. "Directory not allowed" errors

   • Check your allowed_directories configuration
   • Ensure the directory exists and is accessible

3. Commands timing out

   • Increase the timeout value in configuration
   • Check if the command is actually long-running

4. Server not connecting

   • Restart Claude Desktop completely
   • Check the MCP server logs in Claude Desktop
   • Verify JSON syntax in configuration files

Debugging

Enable debug logging by setting the environment variable:

export SHELL_MCP_LOG_LEVEL=DEBUG

Getting Help

1. Check the Issues page
2. Create a new issue with:
   • Your configuration file
   • Error messages from Claude Desktop
   • Steps to reproduce the problem

Development

Local Development

git clone https://github.com/jeffwikstrom/shell-mcp-server.git
cd shell-mcp-server
python3 -m venv venv
source venv/bin/activate
pip install -e .

Running Tests

pip install pytest pytest-asyncio
pytest

Building Distribution

pip install build
python -m build

Security Considerations

• Always review the allowed directories and blocked commands
• Consider running in a sandboxed environment for additional security
• Monitor command execution logs
• Keep the package updated

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Changelog

v1.0.0

• Initial release
• Basic shell command execution
• Safety restrictions
• Configurable settings