mcp-shell 🐚

mcp-shell

可运行 shell 命令的 MCP 服务。你的大模型可以使用一个工具；你可以控制运行哪些命令，以及如何运行。

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

---

运行

Docker（最简单）：

docker run -it --rm -v /tmp/mcp-workspace:/tmp/mcp-workspace sonirico/mcp-shell:latest

从源码运行：

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

---

配置

默认启用安全模式。 没有配置文件时，mcp-shell 会以安全模式启动，并且只注册类型化工具：文件读取、grep/glob、git 检查，以及（选择启用的）文件/git 写入和由运维人员定义的脚本。不会提供原始 shell 命令。只有在需要更改以下默认设置时，才需要配置文件。若要不受限制地运行，必须明确选择启用：

MCP_SHELL_ALLOW_UNSAFE=1 mcp-shell   # disables secure mode; the only tool is shell_exec

若要自定义策略，请指定 YAML 配置：

export MCP_SHELL_SEC_CONFIG_FILE=/path/to/security.yaml
mcp-shell

安全模式（默认）——仅提供类型化工具，所有路径都限制在 working_directory 内：

security:
  enabled: true
  working_directory: /tmp/mcp-workspace
  max_execution_time: 30s
  max_output_size: 1048576
  run_as_user: ""
  audit_log: true

  # Expose file and git write tools (write_file, edit_file, mkdir, move,
  # delete, git_add, git_commit, git_switch, git_restore, git_stash). Off by
  # default.
  writes_enabled: false

  # Operator-defined scripts exposed through the run_script tool. The client
  # picks a name; the argv is yours and cannot be altered.
  # scripts:
  #   test: ["go", "test", "./..."]
  #   lint: ["golangci-lint", "run"]

---

连接

Claude Desktop — 添加到 MCP 配置中：

{
  "mcpServers": {
    "shell": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "sonirico/mcp-shell:latest"],
      "env": { "MCP_SHELL_LOG_LEVEL": "info" }
    }
  }
}

如需自定义配置，请挂载文件并设置环境变量：

{
  "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"]
}

---

工具

安全模式（默认）会注册以下类型化工具。* 表示必需参数。

工具	参数	可用情况
read_file	path*, offset, limit, tail	始终可用
list_dir	path, depth, include_hidden	始终可用
glob	pattern*, path, newer_than, max_results	始终可用
grep	pattern*, path, glob, ignore_case, context, files_only, count, max_results	始终可用
stat	path*	始终可用
diff_files	path_a*, path_b*	始终可用
system_info		始终可用
git_status		始终可用
git_log	max_count, ref, path, author, grep, since, until, oneline, follow	始终可用
git_diff	ref, ref_to, staged, path, stat_only, name_only	始终可用
git_show	ref, path, stat_only	始终可用
git_blame	path*, ref, line_start, line_end	始终可用
git_branches	all, merged	始终可用
git_tags	pattern	始终可用
git_rev_parse	ref*	始终可用
git_ls_files	path, untracked	始终可用
git_stash_list		始终可用
git_remotes		始终可用
write_file	path*, content*, append	writes_enabled
edit_file	path*, old_string*, new_string*, replace_all	writes_enabled
mkdir	path*	writes_enabled
move	from*, to*	writes_enabled
delete	path*, recursive	writes_enabled
git_add	paths, all	writes_enabled
git_commit	message*, all	writes_enabled
git_switch	branch*, create	writes_enabled
git_restore	paths*, staged	writes_enabled
git_stash	action*, message	writes_enabled
run_script	name*	scripts

每个路径参数都会基于 working_directory 解析（跟随符号链接）；任何指向其外部的路径都会被拒绝。Git 路径和引用会按位置传递并经过验证：以 - 开头的引用会被拒绝。没有网络工具；不提供 push、fetch 和 clone。

不受限制模式：只有在设置 MCP_SHELL_ALLOW_UNSAFE=1 时才会启用 shell_exec；它会按设计通过 bash -c 运行命令，不进行验证，而且在该模式下只会注册这一个工具。

---

环境变量

变量	说明
MCP_SHELL_SEC_CONFIG_FILE	安全 YAML 文件的路径（覆盖内置安全默认设置）
MCP_SHELL_ALLOW_UNSAFE	设置为 1（或 true）以禁用安全模式，并用 shell_exec 替代类型化工具（选择启用）
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

---

开发

make install dev-tools   # deps + goimports, golines
make fmt test lint
make docker-build       # build image locally
make release            # binary + docker image

---

安全

• 默认：安全模式。服务会自行构建每个命令的 argv；客户端不会提供 shell 字符串。只注册类型化工具。
• 路径限制：每个路径参数都会基于 working_directory 解析，并跟随符号链接；解析到该目录之外的路径会被拒绝。
• Git 加固：路径会放在 -- 之后，引用会放在 --end-of-options 之后，以 - 开头的引用会被拒绝。Git 运行时会设置 GIT_CONFIG_NOSYSTEM=1、GIT_CONFIG_GLOBAL=/dev/null，禁用 core.fsmonitor、core.pager 和 core.hooksPath，并在 log/diff/show/blame 命令中使用 --no-ext-diff --no-textconv。
• 最小化环境：子进程只会获得 PATH、HOME 和 LANG，不会继承服务自身的环境变量，也不会获得 .env 中的机密信息。
• 写入和脚本需显式启用：writes_enabled: true 会开放文件/Git 写入工具；非空的 scripts 映射会开放 run_script。默认情况下，两者均关闭。
• 不受限制：仅通过 MCP_SHELL_ALLOW_UNSAFE=1 启用。唯一注册的工具是 shell_exec，它会直接运行 bash -c，不做任何验证。适合本地开发，其他场景下则有风险。
• Docker：基于 Alpine，以非 root 用户运行。请在生产环境中使用。最好配合操作系统沙箱（只读文件系统、移除特权），实现纵深防御。

威胁模型、保证内容以及漏洞报告的受理范围见 SECURITY.md。提交安全公告前请先阅读。

---

从 0.x 迁移

安全模式不再验证 shell_exec 命令字符串，而是改为开放类型化工具。配置文件中的 security: 块不再接受以下内容：

已移除的键	替代方案
use_shell_execution	无需替代；类型化工具不会调用 shell
allowed_executables	无需替代；每个工具都会运行由服务构建的固定 argv
allowed_commands	无需替代；同上
blocked_commands	无需替代；同上
blocked_patterns	无需替代；同上

如果加载的配置文件仍设置了其中任一项，启动时会报错并指出对应的键。现在已没有“旧版模式”，也不再提供 security-legacy.yaml 示例。如果需要原始 shell 访问权限，请设置 MCP_SHELL_ALLOW_UNSAFE=1 以恢复 shell_exec；此时它不再受 security: 块的任何限制。

---

贡献

Fork 项目、创建分支、运行 make fmt test，然后提交 PR。