MCP Shell 服务器

一个实现了模型上下文协议 (MCP) 的安全 shell 命令执行服务器。 该服务器允许远程执行白名单中的 shell 命令，并支持 stdin 输入。

特性

• 安全命令执行: 仅允许执行白名单中的命令
• 标准输入支持: 通过 stdin 将输入传递给命令
• 全面输出: 返回 stdout、stderr、退出状态和执行时间
• Shell 操作符安全: 验证 shell 操作符 (;, &&, ||, |) 之后的命令
• 超时控制: 设置命令的最大执行时间

在你的 Claude.app 中设置 MCP 客户端

已发布版本

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "shell": {
      "command": "uvx",
      "args": [
        "mcp-shell-server"
      ],
      "env": {
        "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"
      }
    },
  }
}

本地版本

配置

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "shell": {
      "command": "uv",
      "args": [
        "--directory",
        ".",
        "run",
        "mcp-shell-server"
      ],
      "env": {
        "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"
      }
    },
  }
}

安装

pip install mcp-shell-server

用法

启动服务器

ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server
# 或者使用别名
ALLOWED_COMMANDS="ls,cat,echo" uvx mcp-shell-server

ALLOW_COMMANDS (或其别名 ALLOWED_COMMANDS) 环境变量指定允许执行哪些命令。 命令可以用逗号分隔，逗号周围可以有空格。

ALLOW_COMMANDS 或 ALLOWED_COMMANDS 的有效格式：

ALLOW_COMMANDS="ls,cat,echo"          # 基本格式
ALLOWED_COMMANDS="ls ,echo, cat"      # 带有空格 (使用别名)
ALLOW_COMMANDS="ls,  cat  , echo"     # 多个空格

请求格式

# 基本命令执行
{
    "command": ["ls", "-l", "/tmp"]
}

# 带有 stdin 输入的命令
{
    "command": ["cat"],
    "stdin": "Hello, World!"
}

# 带有超时的命令
{
    "command": ["long-running-process"],
    "timeout": 30  # 最大执行时间，以秒为单位
}

# 带有工作目录和超时的命令
{
    "command": ["grep", "-r", "pattern"],
    "directory": "/path/to/search",
    "timeout": 60
}

响应格式

成功响应：

{
    "stdout": "command output",
    "stderr": "",
    "status": 0,
    "execution_time": 0.123
}

错误响应：

{
    "error": "Command not allowed: rm",
    "status": 1,
    "stdout": "",
    "stderr": "Command not allowed: rm",
    "execution_time": 0
}

安全性

该服务器实现了以下安全措施：

1. 命令白名单: 仅允许执行显式允许的命令
2. Shell 操作符验证: shell 操作符 (;, &&, ||, |) 之后的命令也会根据白名单进行验证
3. 无 Shell 注入: 命令直接执行，无需 shell 解释

开发

设置开发环境

1. 克隆仓库

git clone https://github.com/yourusername/mcp-shell-server.git
cd mcp-shell-server

2. 安装依赖项，包括测试需求

pip install -e ".[test]"

运行测试

pytest

API 参考

请求参数

字段	类型	必需	描述
command	string[]	是	命令及其参数，作为数组元素
stdin	string	否	要传递给命令的输入
directory	string	否	命令执行的工作目录
timeout	integer	否	最大执行时间，以秒为单位

响应字段

字段	类型	描述
stdout	string	来自命令的标准输出
stderr	string	来自命令的标准错误输出
status	integer	退出状态码
execution_time	float	执行所花费的时间（以秒为单位）
error	string	错误消息（仅在失败时出现）

要求

• Python 3.11 或更高版本
• mcp>=1.1.0

许可证

MIT 许可证 - 有关详细信息，请参见 LICENSE 文件