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

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'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