A server that uses the Model Context Protocol (MCP) to execute shell commands. It functions as a bridge that allows AI agents to safely execute shell commands.
Configuration
View docs{
"mcpServers": {
"mkusaka-mcp-shell-server": {
"command": "npx",
"args": [
"-y",
"@mkusaka/mcp-shell-server"
]
}
}
}The MCP Shell Server provides a safe bridge to execute shell commands through the Model Context Protocol (MCP). It supports multiple shells, detailed error handling, and logging, enabling AI agents to run single-line or multi-line commands with controlled access to system resources.
You use the MCP Shell Server by connecting an MCP client to the server, then issuing shell commands through the established MCP channel. The server supports running single-line commands and multi-line commands (including heredocs) across common shells such as bash, zsh, fish, powershell, and cmd. You can retrieve system information, list directory contents, inspect files, and execute commands with controlled working directories.
Prerequisites: Node.js and a package manager (npm, yarn, or pnpm) must be installed on your system. Ensure you have network access to install global packages if you plan to use the public MCP shell server package.
npm install -g @mkusaka/mcp-shell-serveryarn global add @mkusaka/mcp-shell-serverpnpm add -g @mkusaka/mcp-shell-serverConfigure the MCP Shell Server as a connected MCP server in your client configuration to enable remote command execution.
{
"mcpServers": {
"shell": {
"command": "npx",
"args": ["-y", "@mkusaka/mcp-shell-server"]
}
}
}If you prefer a locally installed package, you can reference the local path to the server entry point in your client integration settings:
{
"mcpServers": {
"shell": {
"command": "node",
"args": ["/path/to/mcp-shell-server/dist/index.js"]
}
}
}You can also integrate with editors or tools that support MCP by following the configuration patterns above, using the provided command and arguments to start the MCP Shell Server.
The server exposes a shell tool that executes commands in the selected shell, with a defined working directory under your home directory when provided.
Security and safety are important. Always ensure that commands passed to the server are from trusted sources and avoid enabling commands that could modify critical system settings without explicit confirmation.
Basic command execution examples include retrieving system information, echoing text, and listing directory contents. For multi-line input, you can execute heredoc-style commands to feed multi-line data to a shell.
Executes commands in the specified shell, supporting single-line and multi-line inputs, with optional working directory constraints and robust error handling.