Shell Command MCP Server

🚀 Shell Command MCP Server

This is an MCP (Model Context Protocol) server that allows executing shell commands within a Docker container. It provides a secure and isolated working environment for running commands without granting access to the host Docker daemon.

🚀 Quick Start

Prerequisites

• Docker

Using with Claude for Desktop

Add the following configuration to your Claude for Desktop configuration file.

MacOS:

"shell-command": {
  "command": "docker",
  "args": [
    "run",
    "--rm",
    "-i",
    "--mount",
    "type=bind,src=/Users/user-name/MCPHome,dst=/home/mcp",
    "ghcr.io/kaznak/shell-command-mcp:latest"
  ]
}

Replace /Users/user-name/ClaudeWorks with the directory you want to make available to the container.

Windows:

"shell-command": {
   "command": "docker",
   "args": [
      "run",
      "--rm",
      "-i",
      "--mount",
      "type=bind,src=\\\\wsl.localhost\\Ubuntu\\home\\user-name\\MCPHome,dst=/home/mcp",
      "ghcr.io/kaznak/shell-command-mcp:latest"
   ]
}

Some Tips

Operate files in the mounted directory.

✨ Features

• Run shell scripts through a simple MCP interface:
  • Synchronous execution
  • Asynchronous execution with four different modes:
    • complete: Notify when the command is completed.
    • line: Notify for each output line.
    • chunk: Notify for each output data chunk.
    • character: Notify for each output character.
• Kubernetes tools included: kubectl, helm, kustomize, hemfile
• Isolated Docker container environment with non-root users:
  • Host container userid/groupid mapping is implemented. This allows the container to run as the same user as the host, ensuring that files created by the container have the same owner and permissions as those on the host.
  • Mount the host directory to the /home/mcp directory in the container for persistent storage. It becomes the home directory for AI work.
  • If the host directory is empty, start with the backup initial files in the container.

📚 Documentation

This MCP server provides a working environment similar to that of humans for AI. Authorization is not restricted by MCP functionality but by container isolation and external authorization. It provides more general tools such as shell script execution, so they can be used without specialized knowledge of tool usage. The server implementation is kept as simple as possible to facilitate code review.

💻 Usage Examples

Available MCP Tools

• execute-bash-script-sync
• execute-bash-script-async

🔧 Technical Details

• The MCP server runs as a non-root user within the container.
• The container does not have access to the host Docker daemon.
• The user workspace is mounted from the host for persistent storage.

📄 License

MIT