CLI MCP Server

CLI MCP Server

---

包括的なセキュリティ機能を備え、制御されたコマンドライン操作を実行するための、安全な Model Context Protocol（MCP）サーバー実装です。

---

目次

1. 概要
2. 機能
3. 設定
4. 利用可能なツール
   • run_command
   • show_security_rules
5. Claude Desktop での使用方法
   • 開発中／未公開サーバーの設定
   • 公開済みサーバーの設定
6. セキュリティ機能
7. エラー処理
8. 開発
   • 前提条件
   • ビルドと公開
   • デバッグ
9. ライセンス

---

概要

この MCP サーバーは、コマンドのホワイトリスト、パスの検証、実行制御などの堅牢なセキュリティ対策を備え、安全なコマンドライン実行を可能にします。セキュリティを維持しながら、LLM アプリケーションに制御された CLI アクセスを提供するのに最適です。

機能

• 🔒 厳密な検証による安全なコマンド実行
• ⚙️ 「all」オプションを使用した、コマンドとフラグのホワイトリスト設定
• 🛡️ パストラバーサルの防止と検証
• 🚫 シェル演算子のインジェクション防止
• ⏱️ 実行タイムアウトと長さ制限
• 📝 詳細なエラー報告
• 🔄 非同期操作のサポート
• 🎯 作業ディレクトリの制限と検証

設定

環境変数を使用してサーバーを設定します。

変数	説明	デフォルト
ALLOWED_DIR	コマンド実行のベースディレクトリ（必須）	なし（必須）
ALLOWED_COMMANDS	許可するコマンドをカンマ区切りで指定、または「all」	ls,cat,pwd
ALLOWED_FLAGS	許可するフラグをカンマ区切りで指定、または「all」	-l,-a,--help
MAX_COMMAND_LENGTH	コマンド文字列の最大長	1024
COMMAND_TIMEOUT	コマンドの実行タイムアウト（秒）	30
ALLOW_SHELL_OPERATORS	シェル演算子（&&、||、|、> など）を許可する	false

注：ALLOWED_COMMANDS または ALLOWED_FLAGS に「all」を設定すると、それぞれ任意のコマンドまたはフラグが許可されます。

インストール

Smithery を使って、Claude Desktop 用の CLI MCP Server を自動的にインストールするには：

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

利用可能なツール

run_command

許可されたディレクトリ内で、ホワイトリストに登録された CLI コマンドを実行します。

入力スキーマ：

{
  "command": {
    "type": "string",
    "description": "Single command to execute (e.g., 'ls -l' or 'cat file.txt')"
  }
}

セキュリティに関する注意：

• シェル演算子（&&、|、>、>>）はデフォルトではサポートされていませんが、ALLOW_SHELL_OPERATORS=true で有効にできます
• ALLOWED_COMMANDS='all' でない限り、コマンドはホワイトリストに登録されている必要があります
• ALLOWED_FLAGS='all' でない限り、フラグはホワイトリストに登録されている必要があります
• すべてのパスは ALLOWED_DIR 内にあることが検証されます

show_security_rules

現在のセキュリティ設定と制限を表示します。以下が含まれます。

• 作業ディレクトリ
• 許可されたコマンド
• 許可されたフラグ
• セキュリティ制限（コマンドの最大長とタイムアウト）

Claude Desktop での使用方法

~/Library/Application\ Support/Claude/claude_desktop_config.json に追加します：

開発版／未公開サーバーの設定

{
  "mcpServers": {
    "cli-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path/to/the/repo>/cli-mcp-server",
        "run",
        "cli-mcp-server"
      ],
      "env": {
        "ALLOWED_DIR": "</your/desired/dir>",
        "ALLOWED_COMMANDS": "ls,cat,pwd,echo",
        "ALLOWED_FLAGS": "-l,-a,--help,--version",
        "MAX_COMMAND_LENGTH": "1024",
        "COMMAND_TIMEOUT": "30",
        "ALLOW_SHELL_OPERATORS": "false"
      }
    }
  }
}

公開済みサーバーの設定

{
  "mcpServers": {
    "cli-mcp-server": {
      "command": "uvx",
      "args": [
        "cli-mcp-server"
      ],
      "env": {
        "ALLOWED_DIR": "</your/desired/dir>",
        "ALLOWED_COMMANDS": "ls,cat,pwd,echo",
        "ALLOWED_FLAGS": "-l,-a,--help,--version",
        "MAX_COMMAND_LENGTH": "1024",
        "COMMAND_TIMEOUT": "30",
        "ALLOW_SHELL_OPERATORS": "false"
      }
    }
  }
}

動作しない場合や UI に表示されない場合は、uv clean でキャッシュをクリアしてください。

セキュリティ機能

• ✅ 「all」オプションによるコマンドの許可リスト適用
• ✅ 「all」オプションによるフラグの検証
• ✅ パストラバーサルの防止と正規化
• ✅ シェル演算子のブロック（ALLOW_SHELL_OPERATORS=true によるオプトインをサポート）
• ✅ コマンドの長さ制限
• ✅ 実行タイムアウト
• ✅ 作業ディレクトリの制限
• ✅ シンボリックリンクの解決と検証

エラー処理

サーバーは以下の詳細なエラーメッセージを提供します：

• セキュリティ違反（CommandSecurityError）
• コマンドのタイムアウト（CommandTimeoutError）
• 無効なコマンド形式
• パスのセキュリティ違反
• 実行失敗（CommandExecutionError）
• 一般的なコマンドエラー（CommandError）

開発

前提条件

• Python 3.10+
• MCP プロトコルライブラリ

ビルドと公開

パッケージを配布できる状態にするには：

1. 依存関係を同期し、ロックファイルを更新します：

   uv sync
   

2. パッケージの配布物をビルドします：

   uv build
   

   これにより、ソース配布物とホイール配布物が dist/ ディレクトリに作成されます。

3. PyPI に公開します：

   uv publish --token {{YOUR_PYPI_API_TOKEN}}
   

デバッグ

MCP サーバーは stdio 経由で実行されるため、デバッグが難しい場合があります。最適なデバッグ体験のため、MCP Inspector の使用を強くおすすめします。

以下のコマンドを使用して、npm 経由で MCP Inspector を起動できます：

npx @modelcontextprotocol/inspector uv --directory {{your source code local directory}}/cli-mcp-server run cli-mcp-server

起動すると、Inspector に URL が表示されます。その URL にブラウザーからアクセスすると、デバッグを開始できます。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については LICENSE ファイルをご覧ください。

---

詳細情報やサポートが必要な場合は、プロジェクトのリポジトリで issue を作成してください。