MCP Server Shell Exec

🚀 Shell 実行 MCP サーバ

Model Context Protocol (MCP) を使用した、持続的なシェルコマンド実行機能を提供するサーバです。Claude やその他の MCP 互換の AI アシスタントに適しています。

🚀 クイックスタート

このサーバは、持続的なシェルコマンド実行機能を提供し、Claude やその他の MCP 互換の AI アシスタントと連携して使用できます。

✨ 主な機能

• 持続的なシェルセッション：同じセッション内でコマンド間の状態を維持します。
• バックグラウンド実行：適切なプロセス管理でコマンドをバックグラウンドで実行します。
• クロスプラットフォーム対応：macOS、Linux、Windows で適切なシェルと共に使用できます。
• タイムアウト制御：コマンド実行のタイムアウト時間を設定し、長時間のハングを防止します。
• セッションリセット：必要に応じてシェルセッションをリセットできます。

📦 インストール

# リポジトリをクローン
git clone https://github.com/samihalawa/mcp-server-shell-exec.git
cd mcp-server-shell-exec

# 依存関係をインストール
npm install

# サーバをビルド
npm run build

💻 使用例

基本的な使用法

サーバの起動

npm start

設定

サーバを MCP 設定に追加します：

{
  "servers": {
    "shell-exec-server": {
      "command": "/path/to/node",
      "args": ["/path/to/mcp-server-shell-exec/build/index.js"],
      "enabled": true,
      "port": 3006,
      "environment": {
        "NODE_PATH": "/path/to/node_modules",
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

高度な使用法

利用可能なツール

execute-command

持続的なシェルセッションでシェルコマンドを実行します。

パラメータ：

• command (string, 必須)：実行するシェルコマンド
• runInBackground (boolean, オプション)：コマンドをバックグラウンドで実行するかどうか。デフォルト値：false
• timeoutMs (number, オプション)：コマンドのタイムアウト時間（ミリ秒）。デフォルト値：30000

戻り値：

• success (boolean)：コマンドが正常に実行されたかどうか
• output (string)：コマンドの実行結果

reset-shell

シェルセッションをリセットします。この操作により、現在のセッションが終了し、新しいセッションが開始されます。

パラメータ：なし

戻り値：

• success (boolean)：シェルセッションが正常にリセットされたかどうか
• message (string)：状態メッセージ

サンプルコード

1. 簡単なコマンドを実行する：

   execute-command(command: "ls -la")
   

2. 長時間実行されるタスクをバックグラウンドで実行する：

   execute-command(command: "sleep 60 && echo '完了'", runInBackground: true)
   

3. カスタムタイムアウト時間でコマンドを実行する：

   execute-command(command: "find / -name '*.js'", timeoutMs: 60000)
   

4. シェルセッションをリセットする：

   reset-shell()
   

🔧 技術詳細

サーバは Node.js の node-pty パッケージを使用して、擬似端末を作成し、コマンド間の状態を維持します。これにより、以下のことが可能になります：

• 環境変数がコマンド間で持続する
• 現在の作業ディレクトリが維持される
• バックグラウンドプロセスが継続して実行される
• stdin/stdout の対話が必要なコマンドが正常に動作する

📚 ドキュメント

互換性要件

• Node.js バージョン 14 以上
• node-pty パッケージ
• Claude Desktop、Cursor などの MCP 互換アプリケーションとの互換性

📄 ライセンス

MIT