Skip to main content
Glama
deenesjakoruzh
kg912

shell-mcp

by kg912
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

shell-mcp

一个超安全的 MCP (Model Context Protocol) 服务器，用于与本地 LLM 客户端安全地运行 Shell 命令。

安全模型

命令通过 8 个独立的安全层 —— 每一层都必须通过：

层级

功能

1

Zod 模式验证 — 在任何处理前进行严格的类型检查

2

禁止 Shell 生成 — 使用 execFile 且 shell: false，绝不使用 /bin/sh -c "..."

3

硬编码黑名单 — rm、sudo、dd、curl、brew、docker 等被永久禁止

4

参数检查 — 拒绝元字符、空字节、可疑模式以及特定命令的危险标志

5

目录白名单 — 每个路径必须位于 --allow-dir 内部

6

符号链接解析 — 在路径检查前解析符号链接（防止通过符号链接逃逸）

7

资源限制 — 超时、输出大小上限、并发限制

8

环境清理 — 剥离 AWS_*、*_TOKEN、*_SECRET 以及所有云服务商密钥

Related MCP server: MCP Shell Server

快速开始

# Clone and build
git clone https://github.com/your-username/shell-mcp.git
cd shell-mcp
npm install
npm run build

# Run (must specify at least one --allow-dir)
node dist/index.js --allow-dir ~/projects --allow-dir ~/data

LLM 客户端配置

{
  "shell-mcp": {
    "command": "node",
    "args": [
      "/path/to/shell-mcp/dist/index.js",
      "--allow-dir", "/home/user/projects",
      "--allow-dir", "/home/user/data",
      "--allow-cmd", "ls",
      "--allow-cmd", "cat",
      "--allow-cmd", "grep",
      "--allow-cmd", "find",
      "--allow-cmd", "python3",
      "--timeout", "30",
      "--log-file", "/home/user/.shell-mcp/audit.log"
    ]
  }
}

标志

标志

描述

默认值

--allow-dir <path>

允许的目录（必需，可重复）

无 — 服务器无法启动

--allow-cmd <cmd>

指定允许的命令白名单（可重复）

所有非黑名单命令

--block-cmd <cmd>

额外禁止的命令

—

--timeout <secs>

最大执行时间 (1–300)

30

--max-output <bytes>

最大输出大小

1048576 (1MB)

--max-concurrent <n>

最大并行命令数 (1–10)

3

--log-file <path>

审计日志文件路径

仅 stderr

--enable-write

启用 write_file 工具

关闭

--allow-overwrite

允许覆盖文件

关闭

--read-only-mode

禁用所有写入（覆盖 --enable-write）

关闭

--allow-network-cmds

解锁 curl, wget, nc

关闭

--allow-env-passthrough

将完整环境变量转发给子进程

关闭（已清理）

暴露给 LLM 的工具

run_command

使用显式参数数组运行命令。无 Shell — 管道和重定向将无法工作。

{
  "command": "grep",
  "args": ["-r", "TODO", "/home/user/projects/myapp"],
  "cwd": "/home/user/projects/myapp",
  "timeout": 10
}

read_file

读取文件内容。支持行范围和二进制 (base64) 输出。

{
  "path": "/home/user/projects/myapp/src/main.py",
  "startLine": 1,
  "endLine": 50
}

list_directory

以树状视图、大小和权限列出目录。

{
  "path": "/home/user/projects/myapp",
  "recursive": true
}

write_file (需要 --enable-write)

写入文件。没有 --allow-overwrite 时不会覆盖。

{
  "path": "/home/user/projects/myapp/notes.txt",
  "content": "Hello world"
}

get_server_info

返回当前服务器配置和限制。有助于 LLM 在操作前了解其沙箱环境。

永久禁止的命令

这些命令无法通过任何标志启用：

rm, rmdir, shred, dd, mkfs, fdisk, diskutil, sudo, su, doas,
osascript, defaults, open, launchctl, crontab,
curl, wget, nc, ssh, scp, rsync,
brew, npm, yarn, pip, gem, cargo, docker,
gcc, clang, kill, killall, shutdown, reboot,
gpg, security (macOS keychain), ...and more

审计日志

每个命令尝试（无论允许或拒绝）都会以 JSON 格式记录：

{"timestamp":"2024-01-01T12:00:00.000Z","sessionId":"A3F9B2C1","event":"COMMAND_DENY","command":"rm","args":["-rf","/"],"denyLayer":3,"denyReason":"Command \"rm\" is on the hardcoded blocklist"}
{"timestamp":"2024-01-01T12:00:01.000Z","sessionId":"A3F9B2C1","event":"COMMAND_ALLOW","command":"ls","args":["-la"],"cwd":"/home/user/projects","exitCode":0,"durationMs":12,"outputBytes":1024}

使用 MCP Inspector 检查

npx @modelcontextprotocol/inspector node dist/index.js --allow-dir /tmp/test

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Super Shell MCP Server

    cfdude
    A
    license
    A
    quality
    F
    maintenance
    An MCP server that enables secure execution of shell commands across Windows, macOS, and Linux with built-in whitelisting and approval mechanisms for enhanced security.
    9
    71 npm
    21
    MIT

  • MCP Shell Server

    fastmcp-me
    A
    license
    B
    quality
    D
    maintenance
    Enables secure execution of whitelisted shell commands through MCP, with support for stdin input, timeout control, and comprehensive output including stdout, stderr, and execution time.
    1
    MIT
  • terminal-toolkit-mcp by camel-ai

    terminal-toolkit-mcpofficial

    camel-ai
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables LLM clients to execute shell commands safely through the MCP protocol, with features like session management, safe mode, and process control.
    1
    Apache 2.0

  • Terminal MCP Server

    AcosX
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables executing shell commands on the host system via an MCP tool, with JWT/OAuth authentication and audit logging for secure remote access.
    1
    MIT