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

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

# Install dependencies
npm install

# Build the server
npm run build

Usage

Starting the Server

npm start

Configuration

Add the server to your MCP configuration:

{
  "servers": {
    "shell-exec-server": {
      "command": "/path/to/node",
      "args": ["/path/to/mcp-server-shell-exec/build/index.js"],
      "enabled": true,
      "port": 3006,
      "environment": {
        "NODE_PATH": "/path/to/node_modules",
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

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

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

Run a long-running command in the background:

execute-command(command: "sleep 60 && echo 'Done'", runInBackground: true)

Execute a command with a custom timeout:

execute-command(command: "find / -name '*.js'", timeoutMs: 60000)

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

How It Works

The server uses Node.js's node-pty package to create a pseudo-terminal 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+
node-pty package
Compatible with Claude Desktop, Cursor, and other MCP-compatible applications

License

MIT