@mseep/mac-shell-mcp

Mac Shell MCP Server

An MCP (Model Context Protocol) server for executing macOS terminal commands with ZSH shell. This server provides a secure way to execute shell commands with built-in whitelisting and approval mechanisms.

Features

• Execute macOS terminal commands through MCP
• Command whitelisting with security levels:
  • Safe: Commands that can be executed without approval
  • Requires Approval: Commands that need explicit approval before execution
  • Forbidden: Commands that are explicitly blocked
• Pre-configured whitelist with common safe commands
• Approval workflow for potentially dangerous commands
• Comprehensive command management tools

Installation

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

# Install dependencies
npm install

# Build the project
npm run build

Usage

Starting the Server

npm start

Or directly:

node build/index.js

Configuring in Roo Code and Claude Desktop

Both Roo Code and Claude Desktop use a similar configuration format for MCP servers. Here's how to set up the Mac Shell MCP server:

Using Local Installation

Roo Code Configuration

Add the following to your Roo Code MCP settings configuration file (located at ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json):

"mac-shell": {
  "command": "node",
  "args": [
    "/path/to/mac-shell-mcp/build/index.js"
  ],
  "alwaysAllow": [],
  "disabled": false
}

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json):

"mac-shell": {
  "command": "node",
  "args": [
    "/path/to/mac-shell-mcp/build/index.js"
  ],
  "alwaysAllow": false,
  "disabled": false
}

Replace /path/to/mac-shell-mcp with the actual path where you cloned the repository.

Using NPX (Recommended)

For a more convenient setup that doesn't require keeping a terminal window open, you can publish the package to npm and use it with npx:

Publishing to npm

1. Update the package.json with your details
2. Publish to npm:

   npm publish

Roo Code Configuration

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

Claude Desktop Configuration

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

This approach allows the MCP server to be started automatically by the MCP client without requiring a separate terminal window or manual intervention.

Note:

• For Roo Code: Setting alwaysAllow to an empty array [] is recommended for security reasons, as it will prompt for approval before executing any commands. If you want to allow specific commands without prompting, you can add their names to the array, for example: "alwaysAllow": ["execute_command", "get_whitelist"].
• For Claude Desktop: Setting alwaysAllow to false is recommended for security reasons. Claude Desktop uses a boolean value instead of an array, where false means all commands require approval and true means all commands are allowed without prompting.

Important: The alwaysAllow parameter is processed by the MCP client (Roo Code or Claude Desktop), not by the Mac Shell MCP server itself. The server will work correctly with either format, as the client handles the approval process before sending requests to the server.

Available Tools

The server exposes the following MCP tools:

execute_command

Execute a shell command on macOS.

{
  "command": "ls",
  "args": ["-la"]
}

get_whitelist

Get the list of whitelisted commands.

{}

add_to_whitelist

Add a command to the whitelist.

{
  "command": "python3",
  "securityLevel": "safe",
  "description": "Run Python 3 scripts"
}

update_security_level

Update the security level of a whitelisted command.

{
  "command": "python3",
  "securityLevel": "requires_approval"
}

remove_from_whitelist

Remove a command from the whitelist.

{
  "command": "python3"
}

get_pending_commands

Get the list of commands pending approval.

{}

approve_command

Approve a pending command.

{
  "commandId": "command-uuid-here"
}

deny_command

Deny a pending command.

{
  "commandId": "command-uuid-here",
  "reason": "This command is potentially dangerous"
}

Default Whitelisted Commands

Safe Commands (No Approval Required)

• ls - List directory contents
• pwd - Print working directory
• echo - Print text to standard output
• cat - Concatenate and print files
• grep - Search for patterns in files
• find - Find files in a directory hierarchy
• cd - Change directory
• head - Output the first part of files
• tail - Output the last part of files
• wc - Print newline, word, and byte counts

Commands Requiring Approval

• mv - Move (rename) files
• cp - Copy files and directories
• mkdir - Create directories
• touch - Change file timestamps or create empty files
• chmod - Change file mode bits
• chown - Change file owner and group

Forbidden Commands

• rm - Remove files or directories
• sudo - Execute a command as another user

Security Considerations

• All commands are executed with the permissions of the user running the MCP server
• Commands requiring approval are held in a queue until explicitly approved
• Forbidden commands are never executed
• The server uses Node.js's execFile instead of exec to prevent shell injection
• Arguments are validated against allowed patterns when specified

Extending the Whitelist

You can extend the whitelist by using the add_to_whitelist tool. For example:

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

Using as an npm Package

To use the Mac Shell MCP server with npx similar to other MCP servers like Brave Search, you can publish it to npm or use it directly from GitHub.

Configuration with npx

Add the following to your MCP settings configuration:

Roo Code

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

Claude Desktop

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

This will automatically download and run the server without requiring a manual clone and build process.

Publishing to npm

If you want to publish your own version to npm:

1. Update the package.json with your details
2. Add a "bin" field to package.json:

   "bin": {
     "mac-shell-mcp": "./build/index.js"
   }

3. Publish to npm:

   npm publish

Then you can use it in your MCP configuration:

Roo Code

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

Claude Desktop

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

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.