Skip to main content
Glama
enesjakozh
tumf

mcp-shell-server

by tumf
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

MCP シェル サーバー

コードコフ 鍛冶屋のバッジ

モデルコンテキストプロトコル（MCP）を実装したセキュアシェルコマンド実行サーバー。このサーバーは、標準入力をサポートし、ホワイトリストに登録されたシェルコマンドのリモート実行を可能にします。

特徴

  • 安全なコマンド実行:ホワイトリストに登録されたコマンドのみ実行可能

  • 標準入力サポート: stdin経由でコマンドに入力を渡す

  • 包括的な出力: stdout、stderr、終了ステータス、実行時間を返します。

  • シェル演算子の安全性: シェル演算子 (;、&&、||、|) の後のコマンドを検証します。

  • タイムアウト制御: コマンドの最大実行時間を設定する

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 Server を自動的にインストールするには:

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

手動インストール

pip install mcp-shell-server

Smithery経由でインストール

Smithery経由で Claude Desktop の Shell Server を自動的にインストールするには:

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. シェル演算子の検証: シェル演算子 (;、&&、||、|) の後のコマンドもホワイトリストに対して検証されます。

  3. シェルインジェクションなし: コマンドはシェル解釈なしで直接実行されます

発達

開発環境の設定

  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ファイルを参照

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

NameRequiredDescriptionDefault
stdinNoInput to be passed to the command via stdin
commandYesCommand and its arguments as array
timeoutNoMaximum execution time in seconds; clamped to server maximum
directoryNoOptional working directory. Omit to use the MCP server process current working directory; relative paths are resolved from that same server process CWD.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it discloses OS authority, warns that the allowlist controls executable names rather than program behavior, and gives timeout and output-cap limits. It does not describe return values such as stdout, stderr, exit code, or truncation signaling, which is a meaningful gap for a command execution tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loads the core behavior and security warning. The empty 'Allowed patterns:' line is a small structural blemish that detracts slightly from an otherwise efficient definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a security-sensitive command execution tool with no annotations and no output schema, the definition covers authority, allowlist limits, timeouts, and output cap. It omits return semantics (stdout/stderr/exit code/truncation behavior) and leaves 'Allowed patterns' blank, so it is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by specifying the executable allowlist for the command parameter and the default/max timeout values; however, the empty 'Allowed patterns:' line leaves part of the stated constraint incomplete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: execute an allowed command as an argv array on the MCP server host. It also names the allowlist scope and the commands available, so an agent can immediately tell what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly limits usage to the allowlisted commands (wc, grep, cat, ls, pwd) and notes that commands run with the server process's OS authority. It does not give explicit when-not-to-use guidance, but the allowlist provides strong usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 1 tool updatev1.1.0
    • Changedshell_execute4 fields changed
      • changedInput schema / properties / directory / description
        Previous value: -"Absolute path to a working directory where the command will be executed"New value: +"Optional working directory. Omit to use the MCP server process current working directory; relative paths are resolved from that same server process CWD."
      • changedInput schema / properties / timeout / description
        Previous value: -"Maximum execution time in seconds"New value: +"Maximum execution time in seconds; clamped to server maximum"
      • changedInput schema / properties / timeout / minimum
        Previous value: -0New value: +1
      • changedInput schema / required
        Previous value: -[
-  "command",
-  "directory"
-]New value: +[
+  "command"
+]
  2. 1 tool update
    • First observedshell_execute
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

ActivityActive
ResponsivenessResponsive

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