sonirico/mcp-shell

分类General
作者Community
星标897
定价Free

简介

mcp-shell 是一个让 AI 拥有“操作终端”能力的 MCP 服务端。它不再让 AI 仅仅停留在写代码阶段，而是允许 AI 在受控的隔离环境（如 Docker）中直接执行 Shell 命令。对于开发者来说，这意味着 AI 可以帮你实时运行测试、检查文件系统或部署简单脚本，而无需你手动复制粘贴命令。其核心痛点在于解决了直接在宿主机运行代码的安全顾虑，通过环境隔离确保了操作的可审计性，上手难度低，只要配置好 Docker 即可快速集成到支持 MCP 的客户端中。

核心亮点

  • 赋予 AI 执行 Shell 命令的实际操作能力
  • 基于 Docker 隔离环境，确保系统运行安全
  • 支持多平台部署，实现代码运行闭环
  • 所有指令可审计，方便开发者追踪 AI 行为

完整文档

mcp-shell

![Trust Score](https://archestra.ai/mcp-catalog/sonirico__mcp-shell)
![glama](https://glama.ai/mcp/servers/@sonirico/mcp-shell)

一个用于运行 shell 命令的 MCP server。它为 LLM 提供一个工具，同时让你掌控运行的内容和方式。

基于 mark3labs/mcp-go 构建。使用 Go 编写。

---

运行方式

Docker（最简单）：

bash
docker run -it --rm -v /tmp/mcp-workspace:/tmp/mcp-workspace sonirico/mcp-shell:latest
来自源端：
bash
git clone https://github.com/sonirico/mcp-shell && cd mcp-shell
make install
mcp-shell
---

配置

安全模式（Secure mode）是默认设置。 在没有配置文件的情况下，mcp-shell 将在安全模式下启动，仅限于一个狭小的只读实用程序白名单（ls、cat、grep、find、head、tail ...）。只有在需要扩大或更改该策略时才需要配置文件。若要运行完全无限制模式，您必须显式选择启用：

bash
MCP_SHELL_ALLOW_UNSAFE=true mcp-shell   # disables all validation - do not use in production
若要自定义策略，请指向一个 YAML 配置文件：
bash
export MCP_SHELL_SEC_CONFIG_FILE=/path/to/security.yaml
mcp-shell
Secure mode (推荐) — 无 shell 解析，仅限可执行文件白名单：
yaml
security:
  enabled: true
  use_shell_execution: false
  allowed_executables:
    - ls
    - cat
    - grep
    - find
    - echo
  # WARNING: never add shell/language interpreters (bash, sh, python, perl,
  # ruby, node) or alias-capable tools (git) here - the interpreter executes
  # whatever it is handed, bypassing secure mode entirely. mcp-shell warns at
  # startup if it finds one.
  blocked_patterns:          # optional: restrict args on allowed commands
    - '(^|\s)remote\s+(-v|--verbose)(\s|$)'
  max_execution_time: 30s
  max_output_size: 1048576
  working_directory: /tmp/mcp-workspace
  audit_log: true
Legacy mode — shell 执行，通过命令字符串进行 allowlist/blocklist（如果不小心则易受注入攻击）：
yaml
security:
  enabled: true
  use_shell_execution: true
  allowed_commands: [ls, cat, grep, echo]
  blocked_patterns: ['rm\s+-rf', 'sudo\s+']
  max_execution_time: 30s
  audit_log: true
---

配置连接

Claude Desktop — 添加到你的 MCP 配置：

json
{
  "mcpServers": {
    "shell": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "sonirico/mcp-shell:latest"],
      "env": { "MCP_SHELL_LOG_LEVEL": "info" }
    }
  }
}
对于自定义配置，请挂载该文件并设置环境变量：
json
{
  "command": "docker",
  "args": ["run", "--rm", "-i", "-v", "/path/to/security.yaml:/etc/mcp-shell/security.yaml", "-e", "MCP_SHELL_SEC_CONFIG_FILE=/etc/mcp-shell/security.yaml", "sonirico/mcp-shell:latest"]
}
---

Tool API

| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| command | string | 要运行的 Shell 命令（必填） |
| base64 | boolean | 将 stdout/stderr 编码为 base64（默认：false） |

响应包含 status、exit_code、stdout、stderr、command、execution_time 以及可选的 security_info。

---

Environment variables

| 变量 | 描述 |
|----------|-------------|
| MCP_SHELL_SEC_CONFIG_FILE | 安全 YAML 文件的路径（覆盖内置的安全默认设置） |
| MCP_SHELL_ALLOW_UNSAFE | 设置为 true 以禁用所有验证并运行无限制模式（选择性启用） |
| MCP_SHELL_SERVER_NAME | 服务器名称（默认："mcp-shell 🐚"） |
| MCP_SHELL_LOG_LEVEL | debug, info, warn, error, fatal |
| MCP_SHELL_LOG_FORMAT | json, console |
| MCP_SHELL_LOG_OUTPUT | stdout, stderr, file |

---

Development
bash
make install dev-tools   # deps + goimports, golines

make fmt test lint make docker-build # build image locally make release # binary + docker image
---

Security

  • Default: 安全模式，仅限于一个狭小的只读实用程序 allowlist。无解释器。
  • Secure mode (use_shell_execution: false): 命令被解析为 shell AST，且仅接受单个、完全字面量的简单命令（不支持管道、列表、替换、重定向或 globs）；其可执行文件必须在 allowlist 中。即使在 allowlist 中，解释器 (bash/sh/python) 也会被强制拒绝，且每项工具策略都会剥离逃逸手段 (git -c, find -exec, tar --checkpoint-action)。这是一个早期拒绝层，而非沙箱。
  • Unrestricted: 仅通过 MCP_SHELL_ALLOW_UNSAFE=true 开启。完全访问权限；适用于本地开发，否则具有危险性。
  • Docker: 以非 root 身份运行，基于 Alpine。建议在生产环境中使用。最佳实践是与 OS 沙箱（只读 FS，丢弃 caps）配合使用，以实现深度防御。

---

Contributing

Fork，创建分支，执行 make fmt test，然后提交 PR。

查看官方来源