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