mcp-server-shell-exec

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

# Make the server executable
chmod +x server.js

Usage

Starting the Server

npm start

Configuration

Add the server to your MCP configuration:

macOS/Linux

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

Windows

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

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