# 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)

```bash
pip install shell-mcp-server
```

### Option 2: Install from Source

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

### Option 3: Development Install

```bash
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`

```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:

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

Edit the configuration file:

```json
{
  "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:

```bash
# 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:
```json
{
  "mcpServers": {
    "shell-executor": {
      "command": "/Users/username/.local/share/shell-mcp-server/bin/shell-mcp-server"
    }
  }
}
```

#### Using pipx (Isolated Installation)

```bash
# Install with pipx
pipx install shell-mcp-server
```

Claude Desktop config:
```json
{
  "mcpServers": {
    "shell-executor": {
      "command": "shell-mcp-server"
    }
  }
}
```

#### Using Conda

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

Claude Desktop config:
```json
{
  "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

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `allowed_directories` | Array | See defaults | Directories where commands can be executed |
| `blocked_commands` | Array | See defaults | Command patterns to block |
| `timeout` | Number | 30 | Command timeout in seconds |

### 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:
```bash
export SHELL_MCP_LOG_LEVEL=DEBUG
```

### Getting Help

1. Check the [Issues](https://github.com/jeffwikstrom/shell-mcp-server/issues) page
2. Create a new issue with:
   - Your configuration file
   - Error messages from Claude Desktop
   - Steps to reproduce the problem

## Development

### Local Development

```bash
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

```bash
pip install pytest pytest-asyncio
pytest
```

### Building Distribution

```bash
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