MCP Server Shell Exec

🚀 Shell Execution MCP Server

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

✨ Features

• Persistent Shell Sessions: Maintain the state between commands within the same session.
• Background Execution: Run commands in the background with appropriate process management.
• Cross-Platform Support: Compatible with macOS, Linux, and Windows when used with a suitable shell.
• Timeout Control: Configure the command execution timeout to prevent long-term hanging.
• Session Reset: Reset the Shell session if necessary.

📦 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 Examples

🚀 Quick Start

Start the server

npm start

Configuration

Add the server to the 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 shell commands in a persistent Shell session.

Parameters:

• command (string, required): The shell command to be executed.
• runInBackground (boolean, optional): Whether to run the command in the background. Default: false.
• timeoutMs (number, optional): The timeout for the command in milliseconds. Default: 30000.

Returns:

• success (boolean): Whether the command was executed successfully.
• output (string): The output result of the command execution.

reset-shell

Reset the Shell session. This operation will terminate the current session and start a new one.

Parameters: None

Returns:

• success (boolean): Whether the Shell session was successfully reset.
• message (string): Status information.

Basic Usage

1. Execute a simple command:

   execute-command(command: "ls -la")
   

2. Run a long-running task in the background:

   execute-command(command: "sleep 60 && echo 'Completed'", 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()
   

🔧 Technical Details

The server uses the node-pty package in Node.js to create a pseudo-terminal to maintain the state between commands. This allows:

• Environment variables to persist between commands.
• The current working directory to remain consistent.
• Background processes to continue running.
• Commands that require stdin/stdout interaction to run normally.

Compatibility Requirements

• Node.js version 14 or higher.
• The node-pty package.
• Compatible with MCP-compatible applications such as Claude Desktop and Cursor.

📄 License

MIT