Shell Execution MCP Server

シェル実行 MCP サーバー

Claude およびその他の MCP 互換 AI アシスタントに、シェルコマンドの永続的な実行機能を提供する Model Context Protocol（MCP）サーバーです。

機能

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

インストール

# Clone the repository
git clone https://github.com/samihalawa/mcp-server-shell-exec.git
cd mcp-server-shell-exec

# Install dependencies
npm install

# Make the server executable
chmod +x server.js

使用方法

サーバーの起動

npm start

設定

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

macOS/Linux

{
  "mcpServers": {
    "shell-exec-server": {
      "command": "/path/to/node",
      "args": [
        "/absolute/path/to/mcp-server-shell-exec/server.js"
      ]
    }
  }
}

Windows

{
  "mcpServers": {
    "shell-exec-server": {
      "command": "node",
      "args": [
        "C:\\path\\to\\mcp-server-shell-exec\\server.js"
      ]
    }
  }
}

利用可能なツール

execute-command

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

パラメーター：

• command（文字列、必須）：実行するシェルコマンド
• runInBackground（ブール値、任意）：コマンドをバックグラウンドで実行するかどうか。デフォルト：false
• timeoutMs（数値、任意）：コマンドのタイムアウト時間（ミリ秒）。デフォルト：30000

戻り値：

• success（ブール値）：コマンドの実行に成功したかどうか
• output（文字列）：コマンドの実行結果

reset-shell

シェルセッションをリセットします。現在のセッションを終了し、新しいセッションを開始します。

パラメーター：なし

戻り値：

• success（ブール値）：シェルのリセットに成功したかどうか
• message（文字列）：ステータスメッセージ

使用例

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

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

2. 時間のかかるコマンドをバックグラウンドで実行します：

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

3. カスタムタイムアウトを指定してコマンドを実行します：

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

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

   reset-shell()
   

仕組み

このサーバーは Node.js を使用して、コマンド間の状態を維持するシェルプロセスを作成します。これにより、次のことが可能になります。

• 環境変数をコマンド間で保持する
• 作業ディレクトリを維持する
• バックグラウンドプロセスを実行し続ける
• stdin/stdout を必要とする対話型コマンドを実行する

要件

• Node.js 14+
• Claude Desktop、Cursor、およびその他の MCP 互換アプリケーションに対応

トラブルシューティング

MCP サーバーで問題が発生した場合は、次の点を確認してください。

よくあるエラー：ツールの実行に失敗しました

「Tool execution failed」エラーが表示された場合は、次の点を確認してください。

1. サーバーが正しく実行されていること
2. 設定ファイルで絶対パスを使用していること
3. 設定を変更した後、クライアントアプリケーションを再起動したこと

サーバーのテスト

コマンドを送信して、サーバーを直接テストできます。

echo '{"id":"test1","jsonrpc":"2.0","method":"execute-command","params":{"command":"echo \"Hello World\""}}' | node server.js

出力を含む、適切な形式の JSON レスポンスが返されます。

設定パスに関する問題

設定内のパスを再確認してください。

• 相対パスではなく、絶対パスを使用してください
• Windows ユーザーは、パスにスラッシュ（/）またはエスケープしたバックスラッシュ（\）を使用してください
• サーバーファイルのパスが正しいことを確認してください