Shell MCP Server 使用说明

项目简介

Shell MCP Server 是一个实现了 Model Context Protocol (MCP) 的服务器，它为大型语言模型（LLM）客户端提供安全地执行 shell 命令的功能。通过此服务器，AI 应用可以在预先设定的安全环境中，利用各种 shell 工具与操作系统进行交互，扩展了 AI 应用的能力边界，例如文件操作、系统管理、代码构建等。

主要功能点

安全命令执行: 所有命令都在预先配置的允许目录中执行，防止未授权的系统访问。
多 Shell 支持: 支持多种常见的 shell 环境，如 bash, sh, cmd, PowerShell，满足不同平台和应用的需求。
超时控制: 可以配置命令执行的最大时长，避免长时间运行的命令占用资源或造成阻塞。
跨平台: 同时支持 Unix-like 系统和 Windows 系统。
安全默认: 内置目录和 shell 验证机制，增强安全性。

安装步骤

环境准备: 确保你的系统已安装 Python 3.11 或更高版本。推荐使用 'uv' 包管理器，也可以使用 'pip'。

安装 Shell MCP Server: 打开终端，根据你的包管理器运行以下命令安装 'shell-mcp-server':

# 使用 uv (推荐)
uv pip install shell-mcp-server

# 或者使用 pip
pip install shell-mcp-server

服务器配置

MCP 客户端（如 Claude Desktop）需要配置连接 Shell MCP Server 的信息。以下是一个配置示例，你需要根据你的实际环境进行调整。

{
    "mcpServers": {
        "shell-mcp-server": {  // 服务器名称，客户端用于识别和调用
            "command": "uv",  // 启动服务器的命令，这里假设你已安装 uv 并添加到环境变量
            "args": [ // 启动命令的参数列表
                "run",
                "shell-mcp-server",  // 运行 shell-mcp-server
                "/path/to/allowed/dir1",  // 允许执行命令的目录1，请替换为实际路径
                "/path/to/allowed/dir2",  // 允许执行命令的目录2，可以添加更多允许目录
                "--shell", "bash", "/bin/bash",  // 配置允许使用的 shell: 名称 bash, 路径 /bin/bash
                "--shell", "zsh", "/bin/zsh"   // 配置允许使用的 shell: 名称 zsh, 路径 /bin/zsh，可以配置更多 shell
            ]
        }
    }
}

配置参数说明:

'"shell-mcp-server"': 服务器的名称，可以自定义，客户端通过此名称引用该服务器。
'"command": "uv"': 启动服务器的命令，通常是 Python 虚拟环境中的包管理器或 Python 解释器。如果使用 'pip'，并且 'shell-mcp-server' 已添加到环境变量，可以直接使用 '"command": "shell-mcp-server"'。
'"args": [...]"': 传递给 'shell-mcp-server' 命令的参数列表。
- '"run"', '"shell-mcp-server"': 固定参数，用于运行 'shell-mcp-server'。
- '"/path/to/allowed/dir1"', '"/path/to/allowed/dir2"': 必须配置，指定允许 shell 命令执行的工作目录。请替换为实际的目录路径。安全提示: 仅允许必要的目录，避免开放根目录或敏感目录。
- '"--shell", "bash", "/bin/bash"', '"--shell", "zsh", "/bin/zsh"': 必须配置，指定允许使用的 shell 及其路径。可以配置多个 '--shell' 参数来允许多种 shell。请根据你的系统配置和需求进行设置。

基本使用方法

配置完成后，MCP 客户端可以通过 "shell-mcp-server" 这个服务器名称，调用 'execute_command' 工具来执行 shell 命令。

例如，在客户端中，你可以构造如下的工具调用请求 (Tool Call Request) 来执行命令：

{
  "tool_call": {
    "server_name": "shell-mcp-server",
    "tool_name": "execute_command",
    "arguments": {
      "command": "ls -la",  // 要执行的 shell 命令
      "shell": "bash",      // 使用的 shell 名称，必须是配置中允许的 shell 之一
      "cwd": "/path/to/allowed/dir1" // 命令执行的工作目录，必须是配置中允许的目录之一
    }
  }
}

服务器会执行该命令，并将结果（包括标准输出、标准错误和退出代码）返回给客户端。客户端可以解析返回的结果，并根据需要进行后续处理。

注意:

确保配置的允许目录和 shell 路径是正确的，并且符合安全要求。
客户端在调用 'execute_command' 工具时，'shell' 和 'cwd' 参数的值必须与服务器配置中定义的 shell 名称和允许目录一致。
命令执行的权限与运行 'shell-mcp-server' 服务器进程的用户权限一致。

环境变量配置

可以通过设置环境变量 'COMMAND_TIMEOUT' 来修改命令执行的超时时间（单位为秒，默认 30 秒）。例如，在 Linux/macOS 中，可以在启动服务器前执行 'export COMMAND_TIMEOUT=60' 来将超时时间设置为 60 秒。

关键词