Shell MCP Server 使用说明

项目简介

Shell MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在为 AI 应用程序提供安全可靠的 Shell 命令执行能力。通过此服务器，AI 应用程序可以调用预定义的工具来执行系统命令，从而扩展 AI 的功能，例如文件操作、系统管理、项目构建等。

主要功能点

安全执行: 命令仅在预先配置的允许目录中执行，防止非法访问。
多种 Shell 支持: 支持 bash, sh, cmd, powershell 等多种常用 Shell 环境。
超时控制: 可以配置命令执行超时时间，避免长时间运行的命令阻塞系统。
跨平台: 支持 Unix 和 Windows 系统。
安全默认: 内置目录和 Shell 验证机制，增强安全性。

安装步骤

使用 pip 或 uv (推荐) 安装:

# 使用 pip
pip install shell-mcp-server

# 使用 uv (推荐)
uv pip install shell-mcp-server

服务器配置 (用于 MCP 客户端，例如 Claude Desktop)

要将 Shell MCP Server 集成到 MCP 客户端 (例如 Claude Desktop)，您需要配置客户端以连接到此服务器。以下是一个 Claude Desktop 配置示例，展示了如何配置 'shell-mcp-server'：

{
    "mcpServers": {
        "shell-mcp-server": {  // 服务器名称，客户端用以标识
            "command": "uv",     // 启动服务器的命令，这里使用 uv 运行
            "args": [            // 启动参数列表
                "--directory",   // 指定允许执行命令的目录参数
                "/path/to/shell-mcp-server", // Shell MCP Server 所在目录 (请替换为实际路径)
                "run",           // uv 的 run 命令
                "shell-mcp-server", // 要运行的模块名
                "/path/to/allowed/dir1", // 第一个允许目录 (请替换为实际允许的目录)
                "/path/to/allowed/dir2", // 第二个允许目录 (请替换为实际允许的目录)
                "--shell", "bash", "/bin/bash", // 配置允许的 shell: 名称 "bash", 路径 "/bin/bash"
                "--shell", "zsh", "/bin/zsh"   // 配置允许的 shell: 名称 "zsh", 路径 "/bin/zsh"
            ]
        }
    }
}

配置参数说明:

'server name': 'shell-mcp-server' - 服务器的唯一标识名称。
'command': 启动服务器的命令，例如 'uv', 'python' 等。
'args': 传递给启动命令的参数列表。
- '--directory': 指定允许命令执行的工作目录。可以指定多个。
- '--shell name path': 指定允许使用的 shell 及其路径。可以指定多个。

请务必根据您的实际环境修改 '/path/to/shell-mcp-server', '/path/to/allowed/dir1', '/path/to/allowed/dir2' 等路径以及 shell 的配置。

基本使用方法

一旦 Shell MCP Server 成功配置并运行，MCP 客户端 (例如 Claude Desktop) 就可以通过调用名为 'execute_command' 的工具来执行 shell 命令。

使用 'execute_command' 工具时，您需要提供以下参数：

'command': 要执行的 shell 命令 (字符串)。
'shell': 要使用的 shell 名称 (字符串)，必须是配置中允许的 shell 之一，例如 "bash", "sh", "cmd", "powershell"。
'cwd': 命令执行的工作目录 (字符串)，必须是配置中允许的目录之一。

服务器将执行命令，并返回命令的输出结果 (包括标准输出 stdout, 标准错误 stderr 和退出代码 exit_code)。

关键词