MCP Shell Server

一个实现模型上下文协议（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
# Or using the alias
ALLOWED_COMMANDS="ls,cat,echo" uvx mcp-shell-server

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

ALLOW_COMMANDS 或 ALLOWED_COMMANDS 的有效格式：

ALLOW_COMMANDS="ls,cat,echo"          # Basic format
ALLOWED_COMMANDS="ls ,echo, cat"      # With spaces (using alias)
ALLOW_COMMANDS="ls,  cat  , echo"     # Multiple spaces

请求格式

# 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
}

响应格式

成功响应：

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

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

pip install -e ".[test]"

运行测试

pytest

API参考

请求参数

响应字段

要求

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

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件