Mac Shell MCP 服务器

一个用于通过 ZSH shell 执行 macOS 终端命令的 MCP（Model Context Protocol）服务器。此服务器提供了一种安全的方式来执行 shell 命令，并内置了白名单和审批机制。

功能

• 通过 MCP 执行 macOS 终端命令
• 带有安全级别的命令白名单：
  • 安全：无需批准即可执行的命令
  • 需要批准：在执行前需要明确批准的命令
  • 禁止：被明确阻止的命令
• 预配置的常见安全命令白名单
• 潜在危险命令的审批工作流
• 全面的命令管理工具

安装

# 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

使用

启动服务器

npm start

或者直接：

node build/index.js

在 Roo Code 和 Claude Desktop 中配置

Roo Code 和 Claude Desktop 对 MCP 服务器使用类似的配置格式。以下是设置 Mac Shell MCP 服务器的方法：

使用本地安装

Roo Code 配置

将以下内容添加到您的 Roo Code MCP 设置配置文件中（位于 ~/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 配置

将以下内容添加到您的 Claude Desktop 配置文件中（位于 ~/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
}

将 /path/to/mac-shell-mcp 替换为您克隆仓库的实际路径。

使用 NPX（推荐）

为了更方便地设置并且不需要保持终端窗口打开，您可以将包发布到 npm 并使用 npx：

发布到 npm

1. 更新 package.json 以包含您的详细信息
2. 发布到 npm：

   npm publish
   

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
}

这种方法允许 MCP 服务器由 MCP 客户端自动启动，而无需单独的终端窗口或手动干预。

注意：

• 对于 Roo Code：出于安全原因，建议将 alwaysAllow 设置为空数组 []，这样在执行任何命令之前都会提示批准。如果您希望允许某些命令而不提示，则可以将它们的名称添加到数组中，例如："alwaysAllow": ["execute_command", "get_whitelist"]。
• 对于 Claude Desktop：出于安全原因，建议将 alwaysAllow 设置为 false。Claude Desktop 使用布尔值而不是数组，其中 false 表示所有命令都需要批准，而 true 表示所有命令都无需提示即可执行。

重要：alwaysAllow 参数由 MCP 客户端（Roo Code 或 Claude Desktop）处理，而不是由 Mac Shell MCP 服务器本身处理。服务器可以正确处理任一格式，因为客户端在向服务器发送请求之前会处理审批过程。

可用工具

服务器暴露了以下 MCP 工具：

execute_command

在 macOS 上执行 shell 命令。

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

get_whitelist

获取白名单命令列表。

{}

add_to_whitelist

将命令添加到白名单。

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

update_security_level

更新白名单命令的安全级别。

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

remove_from_whitelist

从白名单中移除命令。

{
  "command": "python3"
}

get_pending_commands

获取待审批的命令列表。

{}

approve_command

批准一个待审批的命令。

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

deny_command

拒绝一个待审批的命令。

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

默认白名单命令

安全命令（无需审批）

• ls - 列出目录内容
• pwd - 打印当前工作目录
• echo - 将文本打印到标准输出
• cat - 连接并打印文件
• grep - 在文件中搜索模式
• find - 在目录层次结构中查找文件
• cd - 更改目录
• head - 输出文件的开头部分
• tail - 输出文件的结尾部分
• wc - 打印行数、单词数和字节数

需要审批的命令

• mv - 移动（重命名）文件
• cp - 复制文件和目录
• mkdir - 创建目录
• touch - 更改文件时间戳或创建空文件
• chmod - 更改文件权限
• chown - 更改文件所有者和组

禁止的命令

• rm - 删除文件或目录
• sudo - 以其他用户身份执行命令

安全注意事项

• 所有命令都以运行 MCP 服务器的用户权限执行
• 需要审批的命令会被放入队列，直到被明确批准
• 禁止的命令永远不会被执行
• 服务器使用 Node.js 的 execFile 而不是 exec 来防止 shell 注入
• 当指定时，参数会根据允许的模式进行验证

扩展白名单

你可以使用 add_to_whitelist 工具来扩展白名单。例如：

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

作为 npm 包使用

要像使用其他 MCP 服务器（如 Brave Search）一样通过 npx 使用 Mac Shell MCP 服务器，你可以将其发布到 npm 或直接从 GitHub 使用。

通过 npx 配置

在你的 MCP 设置配置中添加以下内容：

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
}

这将自动下载并运行服务器，而不需要手动克隆和构建过程。

发布到 npm

如果你想将自己的版本发布到 npm：

1. 更新 package.json 中的详细信息
2. 在 package.json 中添加 "bin" 字段：

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

3. 发布到 npm：

   npm publish
   

然后你可以在你的 MCP 配置中使用它：

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
}

许可证

此MCP服务器依据MIT许可证授权。这意味着您可以根据MIT许可证的条款和条件自由使用、修改和分发该软件。更多详情，请参阅项目仓库中的LICENSE文件。