Skip to main content
Glama
Sign In
enesjakozh
mcp-shell-server

mcp-shell-server

by tumf
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

MCP Shell 服务器

代码验证 铁匠徽章

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

特征

  • 安全命令执行：只能执行白名单命令

  • 标准输入支持：通过 stdin 将输入传递给命令

  • 综合输出：返回 stdout、stderr、退出状态和执行时间

  • Shell 运算符安全：验证 Shell 运算符（;、&&、||、|）后的命令

  • 超时控制：设置命令的最大执行时间

Related MCP server: Shell MCP Server

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"
      }
    },
  }
}

安装

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装 Shell 服务器：

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

手动安装

pip install mcp-shell-server

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装 Shell 服务器：

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

用法

启动服务器

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 许可证 - 详情请参阅许可证文件

Available Tools

1 tool
shell_executeA

Execute an allowed command as an argv array on the MCP server host. Allowed commands run with the server process's OS authority; the allowlist controls executable names, not what an allowed program does. Allowed commands: wc, grep, cat, ls, pwd Allowed patterns: Default timeout: 30s; maximum timeout: 300s; output cap: 1048576 bytes

Inputs: command (required), stdin, timeout, directory.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.2/5.0

    Scored across 1 tool

    Disambiguation5/5

    There is only one tool, so there is no overlap or possibility of misselection. Its purpose—executing an allowlisted shell command—is clear from the name and description.

    Naming Consistency5/5

    The sole tool name, shell_execute, is readable and uses a consistent snake_case style. With only one tool there is no convention mixing to penalize.

    Tool Count3/5

    A single execution tool is enough for a focused shell server, but the surface feels thin: no separate tool for inspecting allowlists, limits, or configuration. It is borderline minimal rather than well-scoped.

    Completeness4/5

    The core operation—running an allowed command—is covered, including timeout and output constraints in the description. However, there are minor gaps such as no tool to list allowed commands or report execution policy details.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Shell-MCP

      kevinwatt
      A
      license
      B
      quality
      D
      maintenance
      A secure MCP server for executing whitelisted shell commands with resource and timeout controls, designed for integration with Claude and other MCP-compatible LLMs.
      20
      389 npm
      7
      MIT

    • Shell MCP Server

      odysseus0
      A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that allows LLMs to execute shell commands and receive their output in a controlled manner.
      7
      MIT

    Appeared in Searches