项目简介

Shemcp（The Simple Shell MCP Server）是一个基于Model Context Protocol (MCP) 构建的后端服务，专注于为AI助手提供一个安全且可控的Shell命令执行环境。它通过严格的命令白名单、目录沙盒、环境变量过滤和资源限制等安全策略，确保AI在执行命令行操作时不会超出预设的权限范围。项目支持大输出分页、临时文件溢出管理，以及便捷的配置和调试功能。

主要功能点

沙盒式命令执行: 所有Shell命令都在限定的沙盒目录（默认为Git仓库根目录）内执行，防止AI访问或修改敏感区域。
精细化安全策略: 支持通过TOML配置文件定义允许/禁止执行的命令模式，过滤环境变量，设置命令超时和最大输出限制。
大输出处理: 自动处理大型命令输出，支持分页读取，或将输出写入临时文件（溢出文件），避免超出LLM的上下文窗口限制。
溢出文件管理: 当命令输出过大时，可将输出自动写入临时文件，并通过专用工具'read_file_chunk'分块读取这些文件内容。
服务器自省: 提供'shell_info'工具，用于获取服务器的沙盒根路径、当前版本以及详细的命令策略（允许/禁止列表）。
多种Shell支持: 能够识别并处理'bash -lc'或'sh -lc'等Shell包装器命令，确保策略能作用于实际执行的命令。

安装步骤

Node.js 环境准备: 确保您的系统已安装Node.js（推荐LTS版本）。
全局安装 (推荐): 打开终端，运行以下命令进行全局安装，这样'shemcp'命令行工具在任何地方都可用。
```
npm install -g shemcp
```
项目内安装 (可选): 如果您希望将其作为特定项目开发依赖，可以在项目根目录运行：
```
npm install -D shemcp
```

配置服务器:

创建Shemcp的配置目录：

mkdir -p ~/.config/shemcp

复制示例配置文件到该目录，并根据您的需求进行编辑：

cp node_modules/shemcp/config.example.toml ~/.config/shemcp/config.toml
# 使用您喜欢的文本编辑器编辑配置文件，例如：
nano ~/.config/shemcp/config.toml

'config.toml'文件允许您定义允许/拒绝的命令正则、沙盒根目录、超时限制等。请仔细审查并根据您的安全需求进行配置。

服务器配置 (面向MCP客户端)

MCP客户端（如Claude Code, Cursor/VS Code的MCP扩展）需要配置如何启动和连接到Shemcp服务器。以下是常见的JSON格式配置示例：

{
  "mcp.servers": {
    "shell": {
      // 服务器名称，客户端将用此名称引用该服务器
      "name": "shell",
      // 启动MCP服务器的命令
      "command": "node",
      // 启动命令的参数。请确保路径是您系统上shemcp安装的绝对路径。
      // 您可以通过 'npm root -g' 找到全局node_modules路径，然后拼接 '/shemcp/dist/index.js'。
      "args": ["/absolute/path/to/global/npm/node_modules/shemcp/dist/index.js"],
      // 环境变量（可选），shemcp会根据其内部白名单过滤，通常不需要额外配置。
      "env": {}
    }
  }
}

提示:

绝对路径: 确保'args'中的'/absolute/path/to/global/npm/node_modules/shemcp/dist/index.js'替换为'shemcp'在您系统上实际安装的'dist/index.js'文件的绝对路径。

Claude Code CLI: 如果您使用Claude Code，可以使用其CLI工具简化配置：

# 假设您知道shemcp dist/index.js的绝对路径
claude mcp add shell -- node /absolute/path/to/shemcp/dist/index.js

基本使用方法

一旦服务器配置并启动，您的LLM客户端（如AI助手）就可以通过调用Shemcp提供的工具进行交互：

执行Shell命令 ('shell_exec'):

{
  "cmd": "git",
  "args": ["status", "--short"],
  "cwd": ".",
  "page": { "cursor": { "cursor_type": "bytes", "offset": 0 }, "limit_bytes": 40000 }
}

此示例将执行'git status --short'命令，并返回前40KB的输出。'cwd'参数指定相对沙盒根目录的工作路径。

读取溢出文件块 ('read_file_chunk'):

{
  "uri": "mcp://tmp/exec-abc123.out",
  "cursor": { "cursor_type": "bytes", "offset": 0 },
  "limit_bytes": 16384
}

此示例将从'shell_exec'生成的URI为'mcp://tmp/exec-abc123.out'的溢出文件中读取前16KB的数据。

获取服务器信息 ('shell_info'):
```
{}
```
- 此示例将返回服务器的沙盒根路径、版本和命令策略等信息。

关键词

项目简介

主要功能点

安装步骤

服务器配置 (面向MCP客户端)

基本使用方法

信息