使用说明

项目简介

MCP Shell Server 是一个基于 Model Context Protocol (MCP) 构建的后端服务，旨在为大型语言模型（LLM）客户端提供安全可控的 Shell 命令执行能力以及系统信息访问能力。它充当 LLM 智能体与底层操作系统之间的桥梁，允许 LLM 通过标准化的 MCP 协议调用 Shell 命令和获取系统资源，从而扩展 LLM 的功能边界，使其能够与环境进行更深入的交互。

主要功能点

Shell 命令执行: 允许 LLM 客户端通过 'shell_exec' 工具执行各种 Shell 命令，支持单行和多行命令，并能处理命令执行的输出和错误。
多种 Shell 支持: 支持 bash, zsh, fish, powershell, cmd 等多种常见的 Shell 环境，具备良好的跨平台兼容性。
详细的错误处理和日志记录: 提供完善的错误处理机制，能够捕获和报告 Shell 命令执行过程中的错误，并记录详细的日志信息，方便问题排查和审计。
系统信息资源访问: 提供 hostname, platform, shell, username, system-info 等多种系统信息资源，允许 LLM 客户端通过标准 URI 访问这些信息，增强 LLM 对运行环境的感知能力。
工作目录限制: 执行 Shell 命令的工作目录被限制在用户 Home 目录下，增强安全性，防止 LLM 误操作或恶意访问敏感系统文件。
兼容 MCP Inspector: 能够与 MCP Inspector 工具配合使用，方便开发者进行调试和测试。

安装步骤

安装 Node.js 和 npm (或 yarn/pnpm)：确保你的系统已安装 Node.js 运行时环境和包管理器 npm、yarn 或 pnpm。
全局安装 MCP Shell Server：
- 使用 npm: 'npm install -g @mkusaka/mcp-shell-server'
- 使用 yarn: 'yarn global add @mkusaka/mcp-shell-server'
- 使用 pnpm: 'pnpm add -g @mkusaka/mcp-shell-server' 或者，你也可以选择从源代码安装：
- 克隆仓库: 'git clone https://github.com/mkusaka/mcp-shell-server.git'
- 进入目录: 'cd mcp-shell-server'
- 安装依赖: 'pnpm install'
- 构建项目: 'pnpm build'

服务器配置

MCP Shell Server 需要在 MCP 客户端中配置才能连接和使用。以下是针对 Cursor 和 Cline 这两个 MCP 客户端的配置示例。你需要在你的 MCP 客户端配置中添加一个名为 "shell" 的服务器，并指定服务器的启动命令和参数。

Cursor 配置 ( '~/.cursor/config.json' ):

{
  "mcpServers": {
    "shell": {
      "command": "npx",
      "args": ["-y", "@mkusaka/mcp-shell-server"]
    }
  }
}

'command': 指定启动 MCP Shell Server 的命令，这里使用 'npx' 来运行全局安装的 '@mkusaka/mcp-shell-server' 包。
'args': 传递给启动命令的参数，这里 '-y' 参数用于 'npx' 自动确认安装包。

Cline 配置 ( Cline MCP settings 文件 ):

macOS: '~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json'
Windows: '%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json'
Linux: '~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json'

{
  "mcpServers": {
    "shell": {
      "command": "npx",
      "args": ["-y", "@mkusaka/mcp-shell-server"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

或者，如果你选择从源代码安装，并希望使用本地安装的包，可以使用以下配置：

{
  "mcpServers": {
    "shell": {
      "command": "node",
      "args": ["/path/to/mcp-shell-server/dist/index.js"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

'command': 指定启动 MCP Shell Server 的命令，这里使用 'node' 运行本地安装包的入口文件 'dist/index.js'。你需要将 '/path/to/mcp-shell-server' 替换为你的实际安装路径。
'args': 传递给启动命令的参数，这里指向入口文件 'dist/index.js'。
'disabled': 设置为 'false' 表示启用该 MCP 服务器。
'autoApprove': 设置为 '[]' 表示默认不自动批准任何工具调用。

基本使用方法

配置完成后，你的 MCP 客户端（如 Cursor 或 Cline）应该能够检测到并连接到 MCP Shell Server。你可以通过以下方式在 LLM 对话中使用 Shell 工具和资源：

Shell 命令执行 ( 'shell_exec' 工具 ): 当 LLM 需要执行 Shell 命令时，它可以使用 'shell_exec' 工具。你需要指示 LLM 使用 'shell_exec' 工具，并提供要执行的 'command' 参数。例如，你可以指示 LLM "请执行命令 'ls -l' 列出当前目录的文件"。
- 工具名称: 'shell_exec'
- 参数:
  - 'command' (string, 必填): 要执行的 Shell 命令。
  - 'workingDir' (string, 可选): 命令执行的工作目录。必须是用户 Home 目录下的子目录。如果不指定，默认使用用户 Home 目录。
示例工具调用 (JSON 格式，由 MCP 客户端发送给服务器):
```
{
  "name": "shell_exec",
  "parameters": {
    "command": "ls -l",
    "workingDir": "/home/your_username/projects"
  }
}
```
访问系统信息资源: LLM 可以通过特定的 URI 访问系统信息资源。例如，要获取主机名，可以使用 'hostname://' URI。
- 可用的资源 URI:
  - 'hostname://' 获取主机名
  - 'platform://' 获取操作系统平台
  - 'shell://' 获取服务器使用的 Shell 路径
  - 'username://' 获取当前用户名
  - 'system-info://' 获取包含主机名、平台、Shell、用户名、CPU 数量、总内存、可用内存、系统运行时间等信息的 JSON 格式数据。
当 LLM 需要访问资源时，MCP 客户端会根据 URI 向服务器请求资源内容。资源内容将以文本或 JSON 格式返回给客户端。

注意事项

安全性: MCP Shell Server 旨在安全地执行 Shell 命令，但仍然需要谨慎使用。避免执行未知的或可能存在风险的命令。工作目录限制在 Home 目录下是为了提高安全性。
错误处理: 如果 Shell 命令执行失败，服务器会返回包含错误信息的响应。请 LLM 能够正确处理错误信息，并向用户报告。
日志: 服务器会将日志信息写入 'mcp-shell.log' 文件，你可以查看日志文件以了解服务器运行状态和命令执行情况。

关键词