local-only server

The server can only run on the client’s local machine because it depends on local resources.

Integrations

Code coverage reporting integration shown by the codecov badge in the README header, displaying test coverage metrics for the project.

MCP シェルサーバー

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

特徴

安全なコマンド実行:ホワイトリストに登録されたコマンドのみ実行可能
標準入力サポート: stdin経由でコマンドに入力を渡す
包括的な出力: stdout、stderr、終了ステータス、実行時間を返します。
シェル演算子の安全性: シェル演算子 (;、&&、||、|) の後のコマンドを検証します。
タイムアウト制御: コマンドの最大実行時間を設定する

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
}

安全

サーバーはいくつかのセキュリティ対策を実装しています。

コマンドホワイトリスト: 明示的に許可されたコマンドのみ実行可能
シェル演算子の検証: シェル演算子 (;、&&、||、|) の後のコマンドもホワイトリストに対して検証されます。
シェルインジェクションなし: コマンドはシェル解釈なしで直接実行されます

発達

開発環境の設定

リポジトリをクローンする

git clone https://github.com/yourusername/mcp-shell-server.git
cd mcp-shell-server

テスト要件を含む依存関係をインストールする

pip install -e ".[test]"

テストの実行

pytest

APIリファレンス

リクエスト引数

分野	タイプ	必須	説明
指示	弦[]	はい	コマンドとその引数を配列要素として
標準入力	弦	いいえ	コマンドに渡される入力
ディレクトリ	弦	いいえ	コマンド実行のための作業ディレクトリ
タイムアウト	整数	いいえ	最大実行時間（秒）

応答フィールド

分野	タイプ	説明
標準出力	弦	コマンドからの標準出力
標準エラー出力	弦	コマンドからの標準エラー出力
状態	整数	終了ステータスコード
実行時間	フロート	実行にかかった時間（秒）
エラー	弦	エラーメッセージ (失敗した場合のみ表示)

要件

Python 3.11以上
mcp>=1.1.0

ライセンス

MITライセンス - 詳細はLICENSEファイルを参照

You must be authenticated.

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

Tools

shell_execute