AI导哈

Shell命令执行服务器

一个安全的Shell命令执行服务器，提供可配置的安全限制和详细的执行日志。

  • by heffrey78
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 heffrey78/shell-mcp-server

使用说明

壳牌MCP服务器

用于安全执行shell命令的模型上下文协议（MCP）服务器。此服务器允许Claude Desktop执行具有可配置安全限制的shell命令。

特性

  • 🔒 安全命令执行：可配置的目录和命令限制
  • ⏱️ 超时保护：防止长时间运行的命令挂起
  • 📝 详细日志记录：全面的执行日志和错误报告
  • ⚙️ 可配置的：可自定义允许的目录和阻止的命令
  • 🐍 简易安装：标准Python包分发

安装

选项1：从PyPI安装（推荐）

pip install shell-mcp-server

选项2：从源代码安装

git clone https://github.com/jeffwikstrom/shell-mcp-server.git
cd shell-mcp-server
pip install .

选项3：开发安装

git clone https://github.com/jeffwikstrom/shell-mcp-server.git
cd shell-mcp-server
pip install -e .

配置

Claude桌面设置

安装后，将以下内容添加到Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Linux/Windows： ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "shell-executor": {
      "command": "shell-mcp-server",
      "env": {
        "SHELL_MCP_CONFIG": "/path/to/your/shell_mcp_config.json"
      }
    }
  }
}

服务器配置（可选）

创建配置文件以自定义服务器行为：

# Create config file
cp shell_mcp_config.template.json ~/.config/shell_mcp_config.json

编辑配置文件：

{
  "allowed_directories": [
    "/Users/username",
    "/Users/username/Projects",
    "/Users/username/Documents",
    "/tmp"
  ],
  "blocked_commands": [
    "rm -rf /",
    "sudo rm",
    "sudo shutdown",
    "format",
    "mkfs"
  ],
  "timeout": 30
}

替代配置

使用虚拟环境

如果您更喜欢使用虚拟环境：

# Create virtual environment
python3 -m venv ~/.local/share/shell-mcp-server
source ~/.local/share/shell-mcp-server/bin/activate
pip install shell-mcp-server

Claude桌面配置：

{
  "mcpServers": {
    "shell-executor": {
      "command": "/Users/username/.local/share/shell-mcp-server/bin/shell-mcp-server"
    }
  }
}

使用pipx（独立安装）

# Install with pipx
pipx install shell-mcp-server

Claude桌面配置：

{
  "mcpServers": {
    "shell-executor": {
      "command": "shell-mcp-server"
    }
  }
}

使用Conda

# Create conda environment
conda create -n shell-mcp python=3.11
conda activate shell-mcp
pip install shell-mcp-server

Claude桌面配置：

{
  "mcpServers": {
    "shell-executor": {
      "command": "/path/to/conda/envs/shell-mcp/bin/shell-mcp-server"
    }
  }
}

用法

配置后，您可以要求Claude执行shell命令：

Can you list the files in my Documents directory?
Can you create a new directory called "test-project"?
Can you check the current git status?
Can you run the tests in my project?

安全功能

目录限制

默认情况下，命令只能在以下位置执行：

  • 用户主目录和子目录
  • /tmp 和 /var/tmp

命令筛选

默认情况下，以下命令模式被阻止：

  • rm -rf / （递归删除根）
  • sudo rm （特权删除）
  • sudo shutdown/reboot/halt （系统控制）
  • format, fdisk, mkfs （磁盘格式化）
  • chmod 777 （权限过于宽松）
  • curl | sh, wget | sh （管道执行）

超时保护

命令在30秒后自动终止（可配置）。

配置参考

环境变量

  • SHELL_MCP_CONFIG：配置文件的路径

配置文件选项

选项 类型 默认值 描述
allowed_directories 数组 查看默认值 可以执行命令的目录
blocked_commands 数组 查看默认值 要阻止的命令模式
timeout 数字 30 命令超时（秒）

默认允许的目录

  • $HOME （用户主目录）
  • $HOME/Documents
  • $HOME/Downloads
  • $HOME/Desktop
  • $HOME/Projects
  • $HOME/Development
  • /tmp
  • /var/tmp
  • /~ （波浪扩展边缘情况的回退）

故障排除

常见问题

  1. “找不到命令：shell mcp服务器”

    • 确保软件包已安装： pip list | grep shell-mcp-server
    • 检查安装目录是否在PATH中
    • 在Claude配置中使用可执行文件的完整路径

  2. “不允许目录”错误

    • 检查你的 allowed_directories 配置
    • 确保目录存在并且可访问

  3. 命令超时

    • 增加 timeout 配置中的值
    • 检查命令是否实际长时间运行

  4. 服务器未连接

    • 完全重新启动克劳德桌面
    • 检查Claude Desktop中的MCP服务器日志
    • 验证配置文件中的JSON语法

调试

通过设置环境变量启用调试日志记录：

export SHELL_MCP_LOG_LEVEL=DEBUG

获取帮助

  1. 检查 问题 页
  2. 使用以下内容创建新问题：
    • 您的配置文件
    • 来自Claude Desktop的错误消息
    • 重现问题的步骤

发展

地方发展

git clone https://github.com/jeffwikstrom/shell-mcp-server.git
cd shell-mcp-server
python3 -m venv venv
source venv/bin/activate
pip install -e .

运行测试

pip install pytest pytest-asyncio
pytest

建筑分布

pip install build
python -m build

安全考虑

  • 始终检查允许的目录和阻止的命令
  • 考虑在沙盒环境中运行以获得额外的安全性
  • 监视命令执行日志
  • 保持软件包更新

许可证

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

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 添加测试
  5. 提交拉取请求

更新日志

v1.0.0

  • 初始版本
  • 基本shell命令执行
  • 安全限制
  • 可配置设置

相关 MCP