MCP外壳服务器

实现模型上下文协议（MCP）的安全shell命令执行服务器。此服务器允许远程执行白名单shell命令，并支持stdin输入。

特性

• 安全命令执行：只能执行白名单中的命令
• 标准输入支持：通过stdin将输入传递给命令
• 综合产出：返回stdout、stderr、退出状态和执行时间
• 壳牌操作员安全：验证shell运算符（；、&&、||、|）后的命令
• 超时控制：设置命令的最大执行时间

Claude.app中的MCP客户端设置

已发布版本

SHELL``` 1code ~/Library/Application\ Support/Claude/claude_desktop_config.json

JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13{
  "mcpServers": {
    "shell": {
      "command": "uvx",
      "args": [
        "mcp-shell-server"
      ],
      "env": {
        "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"
      }
    },
  }
}

本地版本

配置

SHELL``` 1code ~/Library/Application\ Support/Claude/claude_desktop_config.json

JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16{
  "mcpServers": {
    "shell": {
      "command": "uv",
      "args": [
        "--directory",
        ".",
        "run",
        "mcp-shell-server"
      ],
      "env": {
        "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"
      }
    },
  }
}

安装

通过Smithery安装

通过以下方式自动安装Claude Desktop的Shell Server 史密瑟里:

BASH``` 1npx -y @smithery/cli install mcp-shell-server —client claude

### 手动安装


### 通过Smithery安装


通过以下方式自动安装Claude Desktop的Shell Server [史密瑟里](https://smithery.ai/server/mcp-shell-server):


BASH```
1npx -y @smithery/cli install mcp-shell-server --client claude

手动安装

BASH``` 1pip install mcp-shell-server

### 通过Smithery安装


通过以下方式自动安装Claude Desktop的Shell Server [史密瑟里](https://smithery.ai/server/mcp-shell-server):


BASH```
1npx -y @smithery/cli install mcp-shell-server --client claude

用法

启动服务器

BASH``` 1 2 3ALLOW_COMMANDS=“ls,cat,echo” uvx mcp-shell-server

Or using the alias

ALLOWED_COMMANDS=“ls,cat,echo” uvx mcp-shell-server

这 `ALLOW_COMMANDS` （或其别名 `ALLOWED_COMMANDS` )环境变量指定允许执行哪些命令。命令之间可以用逗号分隔，两边可以有空格。


ALLOW_COMMANDS或ALLOWED_COMMANDS的有效格式：


BASH```
1
2
3ALLOW_COMMANDS="ls,cat,echo"          # Basic format
ALLOWED_COMMANDS="ls ,echo, cat"      # With spaces (using alias)
ALLOW_COMMANDS="ls,  cat  , echo"     # Multiple spaces

请求格式

PYTHON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20# Basic command execution { “command”: [“ls”, “-l”, “/tmp”] }

Command with stdin input

{ “command”: [“cat”], “stdin”: “Hello, World!” }

Command with timeout

{ “command”: [“long-running-process”], “timeout”: 30 # Maximum execution time in seconds }

Command with working directory and timeout

{ “command”: [“grep”, “-r”, “pattern”], “directory”: “/path/to/search”, “timeout”: 60 }

### 响应格式


成功响应：


JSON```
1
2
3
4
5
6{
    "stdout": "command output",
    "stderr": "",
    "status": 0,
    "execution_time": 0.123
}

错误响应：

JSON``` 1 2 3 4 5 6 7{ “error”: “Command not allowed: rm”, “status”: 1, “stdout”: "", “stderr”: “Command not allowed: rm”, “execution_time”: 0 }

## 安全


服务器实施了多种安全措施：


1. **命令白名单**：只能执行明确允许的命令
2. **壳牌操作员验证**：shell运算符（；、&&、||、|）后的命令也会根据白名单进行验证
3. **无外壳注射**：命令直接执行，无需shell解释


## 发展


### 建立开发环境


1. 克隆存储库


BASH```
1
2git clone https://github.com/yourusername/mcp-shell-server.git
cd mcp-shell-server

1. 安装依赖项，包括测试要求

BASH``` 1pip install -e ”.[test]“

### 运行测试


BASH```
1pytest

api参考

请求参数

字段	类型	必填	描述
command	string[]	Yes	命令及其参数作为数组元素
stdin	string	否	要传递给命令的输入
directory	string	No	命令执行的工作目录
timeout	整数	否	最大执行时间（秒）

响应字段

字段	类型	描述
stdout	string	命令的标准输出
stderr	string	命令输出的标准错误
状态	整数	退出状态代码
execution_time	float	执行所用的时间（秒）
error	string	错误消息（仅在失败时显示）

需求

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

许可证

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