mcp-shell

MCP Shell Server implements a bridge that lets AI agents safely execute shell commands through the MCP framework. It supports running commands in multiple shells (bash, zsh, fish, powershell, cmd, etc.) with detailed error handling and logging, and exposes a set of system information resources via MCP inspector compatibility. To use it, configure an MCP client to point to the server under the shell MCP server alias and invoke the shell_exec tool as needed. Typical usage involves sending a command to execute, optionally specifying a working directory under your home directory, and receiving the command output, exit status, and any error messages.

The available tools include the shell_exec operation to run single-line or multi-line commands. You can perform basic command execution like echo, ls, and more complex workflows using heredoc syntax for multi-line commands. The server also exposes system information resources such as hostname, platform, username, and a comprehensive system-info resource that aggregates data like CPU, memory, and uptime. Use the provided resource URIs to obtain environmental context if your task requires it, and rely on the inspector tooling to test and debug MCP integrations during development.

Prerequisites:

• Node.js and npm (for npm-based installation)
• Access to the internet to fetch the MCP shell server package

Installation options:

1. From npm (global install):

# Using npm
npm install -g @mkusaka/mcp-shell-server

# Using yarn
yarn global add @mkusaka/mcp-shell-server

# Using pnpm
pnpm add -g @mkusaka/mcp-shell-server

2. From source (for development):

# Clone the repository
git clone https://github.com/mkusaka/mcp-shell-server.git
cd mcp-shell-server

# Install dependencies
pnpm install

# Build the project
pnpm build

To run directly in development mode after build, you can start the server with:

node dist/index.js
# or as an executable
./dist/index.js

3. If you already have a local build, you can point your MCP configuration to the locally installed binary or to the built dist/index.js as shown in the Cline integration examples.

Tips and common considerations:

• The MCP configuration typically uses a shell called shell and points to the MCP shell server via npx as shown in the Cursor configuration. You can adjust the command/args if you prefer to resolve the server package locally or via a different package manager.
• The server logs to mcp-shell.log, which can help diagnose issues with command execution or shell initialization.
• When assigning the workingDir in shell_exec, ensure the path is under the user’s HOME directory to avoid permission or security issues.
• Use the MCP inspector to explore resources (hostname, platform, shell path, username, system-info) to validate environment context before executing commands.
• If you encounter issues with command permissions or environment differences between shells, test with simple commands first (e.g., echo, pwd) and progressively introduce more complex multi-line commands.
• For integration with tools like Cline, you can either use the published npm package or point to a local build as shown in the examples. Ensure your settings.json includes the correct command/args and that the server is reachable from the integration environment.