Mac Shell MCP

🚀 Mac Shell MCP Server

The Mac Shell MCP Server is a tool that enhances shell functionality on macOS. It integrates the MCP (Multi-Command Protocol) to securely manage and control shell commands.

🚀 Quick Start

The Mac Shell MCP Server provides enhanced shell functionality on macOS by integrating the MCP protocol. It offers features like command classification, approval mechanisms, and permission control for secure shell command management.

✨ Features

The server offers the following key features:

1. Command Classification Management: Categorizes shell commands into three types: safe to use, requires approval, and prohibited.
2. Approval Mechanism: Provides an approval process for high-risk commands to ensure only authorized commands are executed.
3. Permission Control: All commands are executed with the permissions of the user running the server, preventing privilege escalation attacks.
4. Command Queuing: Pending approval commands are stored until explicitly approved or rejected.

📦 Installation

1. Clone the project repository:

   git clone https://github.com/cfdude/mac-shell-mcp.git
   cd mac-shell-mcp
   

2. Install dependencies and build:

   npm install
   npm run build
   

💻 Usage Examples

Basic Usage

Start the server

node build/server.js

Configuration Guide

Using via npx

Add the following configuration to the MCP settings: For Brave Shell:

"mac-shell": {
  "command": "npx",
  "args": ["-y", "github:cfdude/mac-shell-mcp"],
  "alwaysAllow": [],
  "disabled": false
}

Advanced Usage

Custom Installation

1. Install as an npm package:

   npm install -g mac-shell-mcp
   

2. Add to MCP configuration:

   "mac-shell": {
     "command": "mac-shell-mcp",
     "alwaysAllow": [],
     "disabled": false
   }
   

📚 Documentation

Default Configuration

Safe-to-Use Commands

• ls - List directory contents
• pwd - Display the current working directory
• echo - Output text to standard output
• cat - View file contents
• grep - Search for patterns in files
• find - Search the directory hierarchy
• cd - Change directories
• head - Output the beginning of a file
• tail - Output the end of a file
• wc - Display line, word, and byte count statistics

Commands Requiring Approval

• mv - Move or rename files
• cp - Copy files and directories
• mkdir - Create a new directory
• touch - Change file timestamps or create an empty file
• chmod - Modify file permissions
• chown - Change file owner and group

Prohibited Commands

• rm - Delete files or directories
• sudo - Execute commands as another user

Extending the Whitelist

You can add new trusted commands using the MCP tool add_to_whitelist, for example:

{
  "command": "npm",
  "securityLevel": "requires_approval",
  "description": "Node.js package manager"
}

🔧 Technical Details

• Command Execution: All commands are executed with the permissions of the user running the server.
• Approval Process: Commands requiring approval are queued until they are explicitly approved or rejected.
• Command Blocking: Prohibited commands are directly intercepted, and an error message is displayed.

📄 License

No license information provided in the original document.

Project Links

• GitHub Repository
• MCP Protocol Documentation

⚠️ Important Note

All commands are executed with the permissions of the user running the server.

💡 Usage Tip

Pending approval commands are stored until explicitly approved or rejected. Prohibited commands will be directly blocked and an error message will be displayed.