# Shell Execution MCP Server

A Model Context Protocol (MCP) server that provides persistent shell command execution capabilities for Claude and other MCP-compatible AI assistants.

## Features

- **Persistent Shell Session**: Maintains state between commands in the same session
- **Background Execution**: Run commands in the background with proper process management
- **Cross-Platform**: Works on macOS, Linux, and Windows with the appropriate shell
- **Timeout Control**: Configure command execution timeouts to prevent hanging
- **Session Reset**: Ability to reset the shell session if needed

## Installation

```bash
# Clone the repository
git clone https://github.com/samihalawa/mcp-server-shell-exec.git
cd mcp-server-shell-exec

# Install dependencies
npm install

# Make the server executable
chmod +x server.js
```

## Usage

### Starting the Server

```bash
npm start
```

### Configuration

Add the server to your MCP configuration:

#### macOS/Linux
```json
{
  "mcpServers": {
    "shell-exec-server": {
      "command": "/path/to/node",
      "args": [
        "/absolute/path/to/mcp-server-shell-exec/server.js"
      ]
    }
  }
}
```

#### Windows
```json
{
  "mcpServers": {
    "shell-exec-server": {
      "command": "node",
      "args": [
        "C:\\path\\to\\mcp-server-shell-exec\\server.js"
      ]
    }
  }
}
```

### Available Tools

#### execute-command

Execute a shell command in the persistent shell session.

Parameters:
- `command` (string, required): The shell command to execute
- `runInBackground` (boolean, optional): Whether to run the command in the background. Default: false
- `timeoutMs` (number, optional): Timeout in milliseconds for the command. Default: 30000

Returns:
- `success` (boolean): Whether the command executed successfully
- `output` (string): Output from the command execution

#### reset-shell

Reset the shell session. This will kill the current session and start a new one.

Parameters: None

Returns:
- `success` (boolean): Whether the shell was reset successfully
- `message` (string): Status message

## Example Usage

1. Execute a simple command:
   ```
   execute-command(command: "ls -la")
   ```

2. Run a long-running command in the background:
   ```
   execute-command(command: "sleep 60 && echo 'Done'", runInBackground: true)
   ```

3. Execute a command with a custom timeout:
   ```
   execute-command(command: "find / -name '*.js'", timeoutMs: 60000)
   ```

4. Reset the shell session:
   ```
   reset-shell()
   ```

## How It Works

The server uses Node.js to create a shell process that maintains state between commands. This allows for:

- Environment variables to persist between commands
- Working directory to remain consistent
- Background processes to continue running
- Interactive commands that require stdin/stdout

## Requirements

- Node.js 14+
- Compatible with Claude Desktop, Cursor, and other MCP-compatible applications

## Troubleshooting

If you encounter issues with the MCP server, check the following:

### Common Error: Tool Execution Failed

If you see "Tool execution failed" errors, check:

1. That the server is running correctly
2. That your configuration file uses absolute paths
3. That you have restarted your client application after changing the configuration

### Testing the Server

You can test the server directly by sending a command:

```bash
echo '{"id":"test1","jsonrpc":"2.0","method":"execute-command","params":{"command":"echo \"Hello World\""}}' | node server.js
```

This should return a properly formatted JSON response with the output.

### Configuration Path Issues

Double-check the paths in your configuration:
- Use absolute paths instead of relative paths
- For Windows users, use forward slashes (/) or escaped backslashes (\\) in the path
- Verify the server file path is correct