mcp-shell

The MCP Shell Server provides a secure, feature-rich environment for managing shell commands, interactive terminals, and process control via the Model Context Protocol (MCP). It exposes a wide range of MCP tools that enable you to execute commands, manage terminal sessions, handle input and output streams, and monitor system and process metrics. You can connect to the server from an MCP client (e.g., Claude Desktop, VS Code with MCP integration, or Cursor) and issue tool calls such as shell_execute to run commands, terminal_send_input to interact with PTY sessions, and various file management operations. The server supports multiple execution modes (foreground, background, detached, adaptive), pipeline-like command chaining, and advanced security features to sandbox and validate commands.

To use the server via an MCP client, you typically initialize a client transport pointing to the mcp-shell-server endpoint, establish a client with the appropriate capabilities, and then perform tool calls like:

• shell_execute to run a shell command and stream output
• terminal_create_session and terminal_send_input to interact with interactive terminals
• get_cleanup_suggestions and perform_auto_cleanup for automated file maintenance
• A variety of file and process management tools for secure operations Refer to the provided examples in the README for concrete MCP client requests and response formats. After connecting, you can execute commands, observe real-time output, and utilize the intelligent guidance and safety features when commands transition to background or require complex handling.

Prerequisites:

• Node.js 18+. Ensure node and npm are in your PATH.
• Git (for cloning the repository or accessing sources).

Installation methods:

Option A: Global installation (recommended for CLI usage)

1. Install the MCP Shell Server globally: npm install -g @mako10k/mcp-shell-server
2. Verify the CLI is available: mcp-shell-server --version mcp-shell-server --help

Option B: Local development / manual installation

1. Clone the repository: git clone https://github.com/mako10k/mcp-shell-server.git
2. Navigate to the project folder: cd mcp-shell-server
3. Install dependencies: npm install
4. Build the project (if applicable): npm run build
5. Run locally for development: npm start

Option C: Local linking for user-level usage (no sudo required)

1. After building, link the package: npm link
2. Run the server via the linked CLI: mcp-shell-server --help

If you prefer the MCP config approach, you can use npx with the package name as shown in the mcp_config example to run the server on demand.

Tips and considerations:

• The server emphasizes security with sandboxing and command validation; you can enable enhanced safety by configuring MCP_SHELL_SECURITY_MODE in your environment.
• Environment-based configuration (MCP_SHELL_SECURITY_MODE, MCP_SHELL_ELICITATION) allows fine-grained control over safety prompts and guidance for complex commands.
• The server exposes 18+ MCP tools for comprehensive shell and process management, including terminal sessions, file operations, and monitoring.
• If you install globally, you can launch the server directly with mcp-shell-server; alternatively, you can invoke it via npx to avoid global installs.
• When integrating with editors like VS Code or Claude Desktop, you can provide appropriate MCP JSON configuration to point to the mcp-shell-server executable and customize environment variables per workspace.
• Ensure your environment has the necessary permissions for sandboxed operations to prevent permission-related issues in restricted environments.