mcp-shell 是一个实现了 Model Context Protocol (MCP) 的后端服务，旨在通过标准化的协议，安全地连接人工智能系统与你的 shell 环境。它将系统 shell 功能封装成一个可供 LLM 调用的工具，支持自动化工作流和工具辅助推理。

主要功能点

安全的命令执行： 支持配置命令白名单、黑名单以及基于正则表达式的模式匹配，严格控制可执行的命令。
执行限制： 可设置命令的最大执行时间和输出内容大小限制，防止资源滥用。
环境控制： 支持指定命令的运行用户和工作目录，增强隔离性。
审计日志： 记录完整的命令执行日志，便于追踪和审计。
结构化响应： 命令执行结果以结构化的 JSON 格式返回，包含标准输出、标准错误、退出码和执行元数据。
二进制数据支持： 可选地将标准输出和标准错误内容进行 Base64 编码，以便处理二进制输出。
易于部署： 提供 Docker 支持，方便在隔离环境中安全部署。

安装步骤

前提条件： 确保已安装 Go 1.23 或更高版本，以及 Git (通常在 Linux, macOS, WSL 等 Unix-like 系统上运行)。如果使用 Docker 部署，需要安装 Docker。

克隆仓库：

git clone https://github.com/sonirico/mcp-shell
cd mcp-shell

构建并安装：

安装到系统路径：
```
make install
```

或者只构建二进制文件：

make build
# 然后可以手动将生成的 mcp-shell 二进制文件移动到 PATH 中的目录
# 例如：sudo mv mcp-shell /usr/local/bin/

（可选）构建 Docker 镜像：
```
make docker-build
```

服务器配置 (供 MCP 客户端使用)

mcp-shell 服务器默认通过标准输入输出 (Stdio) 与 MCP 客户端通信。MCP 客户端需要配置如何启动 mcp-shell 进程并与之交互。通常，这需要在 MCP 客户端的配置中指定 mcp-shell 的可执行文件路径 (command) 和可选的启动参数 (args)。

mcp-shell 本身的主要配置（特别是安全配置和日志配置）通过环境变量或配置文件 ('MCP_SHELL_SEC_CONFIG_FILE' 指定的 YAML 文件) 进行。

MCP 客户端配置示例（请参考你的具体 MCP 客户端软件的文档）：

{
  "mcpServers": {
    "your_server_name": { // 在 MCP 客户端内部引用的服务器名称
      "command": "path/to/mcp-shell", // mcp-shell 可执行文件的路径
      "args": [], // 通常不需要启动参数，配置通过环境变量或文件
      "env": { // 设置 mcp-shell 运行所需的环境变量
        "MCP_SHELL_SECURITY_ENABLED": "true", // 启用安全模式
        "MCP_SHELL_SEC_CONFIG_FILE": "/path/to/your/security.yaml", // 指定安全配置文件路径
        "MCP_SHELL_LOG_LEVEL": "info", // 设置日志级别
        "MCP_SHELL_LOG_FORMAT": "json" // 设置日志格式
        // 其他 mcp-shell 支持的环境变量
      }
    }
  }
}

请创建一个 'security.yaml' 文件来配置安全规则（推荐）。例如：

security:
  enabled: true
  allowed_commands: # 允许执行的命令前缀白名单 (如果列表非空，则只允许列表中的命令)
    - ls
    - cat
    - grep
    - find
    - echo
  blocked_patterns: # 基于正则表达式的禁止模式
    - 'rm\s+.*-rf.*'
    - 'sudo\s+.*'
  max_execution_time: 30s # 最大执行时间
  working_directory: /tmp/mcp-workspace # 命令执行的工作目录
  max_output_size: 1048576 # 最大输出大小 (字节)
  audit_log: true # 是否记录审计日志

基本使用方法

安装并配置好安全文件后，MCP 客户端会根据其配置启动 mcp-shell 进程。mcp-shell 启动后，会监听标准输入，等待 MCP 客户端发送符合 MCP 协议的 JSON-RPC 请求。

mcp-shell 提供了一个名为 'shell_exec' 的工具供客户端调用。

工具名称： 'shell_exec'
描述： 执行 shell 命令，支持配置安全约束，返回结构化 JSON 结果。
参数：
- 'command' (string, 必需): 要执行的 shell 命令字符串。
- 'base64' (boolean, 可选, 默认 false): 如果为 true，stdout 和 stderr 将以 Base64 编码返回。

MCP 客户端通过调用 'shell_exec' 工具并提供 'command' 参数来请求 mcp-shell 执行命令。mcp-shell 会根据配置进行安全校验，然后在隔离的环境中执行命令，并将结果以 JSON 格式返回给客户端。

例如，一个 MCP 客户端可能会发送一个 JSON-RPC 请求，其参数包含对 'shell_exec' 工具的调用：

{
  "jsonrpc": "2.0",
  "method": "callTool",
  "params": {
    "tool": "shell_exec",
    "parameters": {
      "command": "ls -l /tmp"
    }
  },
  "id": "request-id-123"
}

mcp-shell 将执行 'ls -l /tmp' 命令，并返回一个包含执行结果（stdout, stderr, exit_code 等）的 JSON-RPC 响应。

关键词

主要功能点

安装步骤

服务器配置 (供 MCP 客户端使用)

基本使用方法

信息