Shemcp-简单的shell mcp服务器。

](https://www.npmjs.com/package/shemcp) ](https://www.npmjs.com/package/shemcp) ![CI](https://github.com/acartine/shemcp/actions/workflows/ci.yml) ![License: MIT](LICENSE)

独立的代理编码，无需交出城堡的钥匙。不要再收到不重要的批准提示。

新特性

Git工作树支持：自动检测并允许访问从沙盒存储库创建的git工作树。工作树通过以下方式进行验证 git worktree list 并加入了本次会议的对抗名单。禁用 worktree_detection = false 在 [security] 配置文件的一部分。
🆕 分页支持：添加了分页和大输出处理 shell_exec 可配置 limit_bytes, limit_lines，以及 on_large_output 模式
🆕 泄漏文件管理：大输出会自动写入临时文件 spill_uri 为了安全、分页阅读
🆕 新 read_file_chunk 工具：使用从溢出文件中读取分页数据 cursor 和 limit_bytes 用于安全流媒体
沙盒根现在默认解析为Git存储库根（回退到当前工作目录），并可通过以下方式进行可选覆盖 SHEMCP_ROOT 或 MCP_SANDBOX_ROOT.
已删除 shell_set_cwd 工具； shell_exec cwd可以是相对于沙箱根的，也可以是沙箱中的绝对路径或有效的git工作树。
添加 shell_info 自省工具（报告 sandbox_root 并解决相对 cwd 输入，包括 within_sandbox 检查）。
硬化 ensureCwd 和 realpath 以及边界检查，以防止符号链接逃逸并确保目录可访问性。
更新文档和测试以反映新行为。

概述

此MCP服务器提供具有全面安全策略的沙盒shell命令执行。它允许AI助手安全地执行shell命令，同时通过可配置的TOML文件实施严格的访问控制。

沙盒根选择

为了避免沙箱意外缩小到嵌套的子目录，shemcp在启动时使用以下优先级导出一个稳定的沙箱根：

SHEMCP_ROOT或MCP_SANDBOX_ROOT环境变量（如果已设置且存在）
从代理的进程中发现的最近Git存储库根。cwd（）
process.cwd（）作为最终回退

所选根在进程期间保持固定。命令执行的工作目录可以是此沙盒内的相对路径，也可以是沙盒内的绝对路径或有效的git工作树。

shellexec可选地接受一个cwd，该cwd可以是相对于沙箱根的，也可以是沙箱内的绝对路径或有效的git工作树。

这确保了如果客户端碰巧启动了几个级别的代理，沙箱仍然会解析到项目根目录（通常是Git根目录），防止MCP无法访问存储库中的兄弟路径。

您可以使用SHEMCP_root或MCP_SANDBOX_root显式覆盖特殊情况下的根。

特性

📋 TOML配置：易于编辑配置文件并进行验证
🔒 命令允许列表：只能执行预先批准的命令
🚫 命令拒绝列表：明确阻止危险的命令模式
📁 沙盒到项目根：默认情况下，命令在Git存储库根目录中运行（回退到当前工作目录）。覆盖 SHEMCP_ROOT 或 MCP_SANDBOX_ROOT.
🌿 Git工作树支持：自动检测并允许访问git工作树（通过创建的兄弟目录 git worktree add)
🛡️ 强化路径执行: cwd 在沙箱/工作树边界内可以是相对的或绝对的。实路径边界检查可防止符号链接逃逸。
🌍 环境过滤：仅传递安全环境变量
⏱️ 资源限制：可配置的超时和输出大小上限
📄 分页支持：通过可配置的方式处理大型命令输出 limit_bytes 和 limit_lines
💾 泄漏文件管理：大输出自动写入临时文件，以便安全、分页访问
🔄 流媒体阅读: read_file_chunk 用于读取令牌安全块中溢出文件的工具

安全模型

服务器实现了多层安全：

命令验证：命令必须匹配满列表模式，而不能匹配denylist模式
目录沙盒：命令只能在沙盒根目录（默认情况下为Git存储库根目录；回退到CWD）或有效的Git工作树中运行。 cwd 在这些边界内可以是相对的或绝对的。通过以下方式覆盖根 SHEMCP_ROOT 或 MCP_SANDBOX_ROOT.
环境隔离：敏感环境变量被过滤掉
资源限制：防止具有超时和输出限制的失控进程

调试

服务器将调试日志写入 ~/.shemcp/debug.log 这可以帮助诊断问题：

# View the debug log
tail -f ~/.shemcp/debug.log

# Clear the debug log
> ~/.shemcp/debug.log

日志记录了：

服务器启动和配置加载
收到所有MCP请求
停机信号和清理过程
任何错误或异常

默认策略

允许的命令：git、gh、make、grep、sed、jq、aws、az、bash-lc
拒绝图案：git推送到主/主分支
根目录：默认情况下为Git存储库根目录（回退到process.cwd（））。通过以下方式覆盖 SHEMCP_ROOT 或 MCP_SANDBOX_ROOT.
超时：每条命令600秒
最大输出功率：每个流2MB（stdout/stderr）

命令

1) `shell_exec`

在沙箱中执行允许列出的命令，支持分页和大输出处理。

参数：

cmd （必填）：运行命令（例如，“git”、“npm”、“python”）
args：字符串参数数组（例如，\[“status”，“--short”\]）
cwd：可选工作目录（相对于沙盒根目录，或沙盒/工作树中的绝对路径）
timeout_ms：命令超时（毫秒）（已弃用，请使用 timeout_seconds)
timeout_seconds：命令超时（秒）（1-600，限制在策略限制范围内）
max_output_bytes：最大输出大小（以字节为单位）（1000-10M，限制在策略限制范围内）
page （必填）：分页配置对象：

- cursor：不透明的位置标记（例如，“字节：0”） - limit_bytes：每页最大字节数（默认值：40000，~10k令牌） - limit_lines：每页最大行数（默认值：2000，以先点击者为准）

on_large_output：如何处理大输出：“溢出”（默认）、“截断”或“错误”

规则：

A. page 必须提供物品；否则，请求将被拒绝 Error: pagination parameters are required
cwd 可以相对于沙箱根，也可以是沙箱中的绝对路径或有效的git工作树
沙盒/工作树边界外的路径被拒绝，并显示明确的错误消息
大输出（>limit_bytes或>limit_lines）根据以下方式处理 on_large_output 模式

响应格式：

{
  "exit_code": 0,
  "stdout_chunk": "first 40k of data...",
  "stderr_chunk": "",
  "bytes_start": 0,
  "bytes_end": 39999,
  "total_bytes": 58112234,
  "truncated": false,
  "next_cursor": "bytes:40000",
  "spill_uri": "mcp://tmp/exec-abc123.out",
  "mime": "text/plain",
  "line_count": 1780,
  "stderr_count": 0,
  "cmdline": ["git", "log"],
  "cwd": "/path/to/project",
  "limits": {
    "timeout_ms": 60000,
    "max_output_bytes": 2000000
  }
}

2) `read_file_chunk`

从由创建的溢出文件中读取分页数据 shell_exec 当 on_large_output 设置为“溢出”。

参数：

uri （必填）：溢出文件的URI（例如，“mcp://tmp/exec-abc123.out")
cursor：不透明位置标记（默认值：“字节：0”）
limit_bytes：要读取的最大字节数（默认值：40000）

响应格式：

{
  "data": "chunk of file content...",
  "bytes_start": 0,
  "bytes_end": 39999,
  "total_bytes": 58112234,
  "next_cursor": "bytes:40000",
  "mime": "text/plain"
}

3) `shell_info`

沙盒的内省实用程序。

参数（可选）：

- cwd：针对沙盒根进行解析和验证的相对路径

返回值：JSON，包括 sandbox_root，如果 cwd 提供， resolved_path 和 within_sandbox 旗帜

4）已删除： `shell_set_cwd`

此命令已被删除。使用 shell_exec 与一位亲戚 cwd 相反。

快速查阅

请您的MCP客户使用以下输入调用这些工具：

shell_info 示例：

- { "cwd": "." } → 回报 sandbox_root，解析到根目录，并在沙盒中确认 - { "cwd": "src" } → 退货已解决 src 路径和 within_sandbox: true 如果存在/内部

shell_exec 示例：

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

{ "cmd": "npm", "args": ["test"], "cwd": ".", "page": { "cursor": { "cursor_type": "bytes", "offset": 0 } } }

{ "cmd": "ls", "args": ["-la"], "cwd": "src", "page": { "cursor": { "cursor_type": "bytes", "offset": 0 } } }

分页示例：

- { "cmd": "git", "args": ["log"], "page": { "cursor": { "cursor_type": "bytes", "offset": 0 }, "limit_bytes": 32768 } } → git日志的前32KB - { "cmd": "cat", "args": ["large.log"], "page": { "cursor": { "cursor_type": "bytes", "offset": 40000 } } } → 从字节40000开始的下一页 - { "cmd": "find", "args": [".", "-name", "*.ts"], "page": { "cursor": { "cursor_type": "bytes", "offset": 0 } }, "on_large_output": "spill" } → 将大型查找结果溢出到文件中

溢出文件读取示例：

- { "uri": "mcp://tmp/exec-abc123.out", "cursor": { "cursor_type": "bytes", "offset": 0 }, "limit_bytes": 16384 } → 读取溢出文件的前16KB - { "uri": "mcp://tmp/exec-abc123.out", "cursor": { "cursor_type": "bytes", "offset": 16384 }, "limit_bytes": 16384 } → 读取下一个16KB块

快速开始

1.克劳德代码的设置

使用Claude Code的CLI和npx添加MCP服务器（推荐）：

# Add the shell MCP server to Claude Code (uses latest version)
claude mcp add shell -- npx -y shemcp@latest

# Verify it was added successfully
claude mcp list

备选范围：

# Add for current project only (default)
claude mcp add shell -- npx -y shemcp@latest

# Add for current user (available in all projects)
claude mcp add --scope user shell -- npx -y shemcp@latest

# Add for project team (creates .mcp.json in project root)
claude mcp add --scope project shell -- npx -y shemcp@latest

2.其他MCP客户端的设置

对于带有MCP的游标/VS代码：

{
  "mcp.servers": {
    "shell": {
      "command": "npx",
      "args": ["-y", "shemcp@latest"],
      "env": {}
    }
  }
}

对于桌面MCP客户端：

命令: npx
参数: ["-y", "shemcp@latest"]

3.可选：自定义配置

服务器使用合理的默认值即可开箱即用。如果需要自定义配置：

# Create config directory
mkdir -p ~/.config/shemcp

# Download and customize the example config
curl -o ~/.config/shemcp/config.toml https://raw.githubusercontent.com/acartine/shemcp/main/config.example.toml

# Edit the config to match your needs
nano ~/.config/shemcp/config.toml

4.替代方案：全局安装（可选）

如果您更喜欢全局安装shemcp而不是使用npx：

# Global installation
npm install -g shemcp

# Then use direct command in MCP config
claude mcp add shell -- shemcp

从源代码开发：

git clone https://github.com/acartine/shemcp.git
cd shemcp
npm install
npm run build

# Add local version to Claude Code
claude mcp add shell -- node /absolute/path/to/shemcp/dist/index.js

配置

服务器使用合理的内置默认值。配置文件包括 可选的 并且只需要定制。

如果存在，配置将从以下位置加载（按优先级顺序）：

~/.config/shemcp/config.toml （用户配置-最高优先级）
/etc/shemcp/config.toml （系统配置-优先级较低）
内置默认值（始终用作回退）

配置结构

# Configuration format version (not the package version)
config_version = 1

[server]
name = "shemcp"

[directories]
# The sandbox root defaults to the Git repository root (fallback to the current
# working directory) and remains fixed for the process lifetime.
# Override with SHEMCP_ROOT or MCP_SANDBOX_ROOT environment variables if needed.

[commands]
allow = ["^git(\\s|$)", "^npm(\\s|$)", "^make(\\s|$)"]
deny = ["^git\\s+push\\s+(origin\\s+)?(main|master)"]

[limits]
timeout_seconds = 600
max_output_bytes = 2000000

[environment]
whitelist = ["PATH", "HOME", "USER", "LANG"]

[security]
require_secure_permissions = false
worktree_detection = true  # Enable automatic git worktree detection

看 config.example.toml 查看带有文档的完整示例。

示例用法

一旦配置了Claude Code或其他MCP客户端，您可以要求AI执行shell命令：

交互示例：

*“检查我的项目的git状态”* → 执行 git status
*“列出所有TypeScript文件”* → 执行 find . -name "*.ts"
*“运行测试”* → 执行 npm test
*“显示最近的提交”* → 执行 git log --oneline -10
*“为此功能创建新分支”* → 执行 git checkout -b feature-name

AI只能执行与您的允许模式匹配的命令，并在您允许的目录中运行，为shell操作提供安全的沙箱。

分页使用场景

处理大型命令输出

在处理产生大输出的命令（如日志、大文件或目录列表）时，使用分页来避免标记限制：

场景1：通过git日志分页

{
  "cmd": "git",
  "args": ["log", "--oneline"],
  "page": { "cursor": { "cursor_type": "bytes", "offset": 0 }, "limit_bytes": 32768 }
}

返回前32KB的git历史记录 next_cursor 为了继续。

场景2：分块读取大文件

{
  "cmd": "cat",
  "args": ["huge.log"],
  "on_large_output": "spill",
  "page": { "cursor": { "cursor_type": "bytes", "offset": 0 }, "limit_bytes": 40000 }
}

溢出大型日志文件并返回前40KB spill_uri 继续阅读。

场景3：处理大型目录列表

{
  "cmd": "find",
  "args": [".", "-type", "f", "-name", "*.js"],
  "page": { "cursor": { "cursor_type": "bytes", "offset": 0 }, "limit_lines": 1000 }
}

最多返回1000行文件列表，以先到者为准。

读取溢出文件

当 shell_exec 返回a spill_uri，使用 read_file_chunk 以可管理的块读取数据：

场景4：读取溢出的输出

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

读取溢出文件的前16KB。

场景5：继续读取溢出的输出

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

使用以下命令读取下一个16KB块 next_cursor 根据之前的回复。

代理行为模式

自动分页循环：

// Pseudo-code for automatic pagination
let result = shell_exec(cmd, args, { page: { limit_bytes: 40000 } });
while (result.next_cursor) {
  // Process current chunk
  processChunk(result.stdout_chunk);

  // Get next chunk
  result = shell_exec(cmd, args, {
    page: { cursor: result.next_cursor }
  });
}

泄漏文件处理：

// Pseudo-code for handling spilled files
let result = shell_exec(cmd, args, { on_large_output: "spill", page: {} });
if (result.spill_uri) {
  let chunk = read_file_chunk(result.spill_uri, 40000);
  while (chunk.next_cursor) {
    processChunk(chunk.data);
    chunk = read_file_chunk(result.spill_uri, chunk.next_cursor);
  }
}

发展

# Run tests
npm test

# Run tests with UI
npm test:ui

# Build TypeScript
npm run build

# Development mode
npm run dev

Git工作树支持

shemcp自动支持git工作树，这些工作树通常用于并行开发工作流。当代理创建工作树时（例如。， git worktree add ../repo-feature -b feature)，工作树被创建为主沙箱外的兄弟目录。

运作原理

当请求沙箱外的路径时，shemcp会检查它是否与工作树命名模式（以沙箱基名开头的兄弟目录）匹配
如果匹配，舍姆普就会跑 git worktree list 验证这是一个合法的工作台
已验证的工作树被添加到会话分配列表中，以便后续高效访问
工作树列表缓存60秒，以尽量减少git命令开销

示例

/Users/user/myproject           # Primary sandbox (git root)
/Users/user/myproject-feature   # Worktree - automatically allowed
/Users/user/myproject-bugfix    # Worktree - automatically allowed
/Users/user/other-project       # NOT allowed - different project

禁用工作树检测

如果您更喜欢更严格的安全性并且不需要工作树支持，请在配置文件中禁用它：

# In ~/.config/shemcp/config.toml
[security]
worktree_detection = false

禁用时，只允许主沙箱根内的路径。

安全考虑

⚠️ 重要安全注意事项：

配置安全：配置文件不应是全局可写的。服务器警告权限不安全。

无项目级配置：按照设计，没有 .shemcp.toml 工作目录中的文件，以防止AI修改其自身的安全约束。

最小特权原则：从限制性设置开始，根据需要逐步添加权限。

定期审计：定期检查您允许的命令和目录。

测试

该项目包括一个全面的测试套件，涵盖：

配置加载和验证
政策执行
命令分配列表/拒绝列表
目录访问控制
环境过滤
工具定义
服务器配置

使用以下工具运行测试： npm test

故障排除

常见问题

“命令不允许”错误：

检查你的 commands.allow 配置中的模式
确保命令与正则表达式模式匹配
验证该命令不在 commands.deny 列表

“不允许目录”错误：

沙箱根是Git项目根（如果没有Git仓库，则为process.cwd（））。所有的路径都必须在里面。
在特殊情况下，使用SHEMCP_ROOT或MCP_SANDBOX_ROOT进行覆盖。
确保目录存在并且可访问。

服务器未连接：

确认您正在使用 npx -y shemcp@latest 在MCP客户端配置中
如果使用本地安装，请检查服务器是否使用 npm run build
在MCP客户端日志中查找错误消息
检查调试日志 ~/.shemcp/debug.log

调试配置

要查看当前配置：

# List Claude Code MCP servers
claude mcp list

# Get details about your shell server
claude mcp get shell

# Remove server if needed
claude mcp remove shell

# Check which config files exist (optional - only if you created custom config)
ls -la ~/.config/shemcp/config.toml
ls -la /etc/shemcp/config.toml

许可证

麻省理工学院

sheMCP (Acartine)

快速接入

详细介绍