Mac Shell MCP server for AI agents

The Mac Shell MCP server provides a secure interface for executing macOS terminal commands through the Model Context Protocol. It includes security features like command whitelisting and approval workflows to protect your system while allowing Claude or other MCP clients to run shell commands on your behalf.

Installation

To install the Mac Shell MCP server:

# 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

Starting the Server

Start the server using either of these methods:

npm start

Or directly:

node build/index.js

Configuration

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:

Roo Code Configuration

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

Claude Desktop Configuration

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

Note: For security reasons, it's recommended to use alwaysAllow: [] (Roo Code) or alwaysAllow: false (Claude Desktop) to require approval for commands.

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

Extending the Whitelist

You can extend the whitelist using the add_to_whitelist tool:

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

Security Considerations

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

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.