Super Shell MCP Server

Super Shell MCP サーバー

Windows、macOS、Linux の複数のプラットフォームでシェルコマンドを実行するための MCP（Model Context Protocol）サーバーです。組み込みのホワイトリストと承認の仕組みにより、シェルコマンドを安全に実行できます。

🎉 Claude Desktop 拡張機能として利用可能になりました！ .dxt パッケージを使えばワンクリックでインストールでき、開発者ツールや設定は不要です。

機能

• Windows、macOS、Linux で MCP 経由のシェルコマンドを実行
• プラットフォームの自動検出とシェルの選択
• 複数のシェルに対応：
  • Windows：cmd.exe、PowerShell
  • macOS：zsh、bash、sh
  • Linux：bash、sh、zsh
• コマンドインジェクションのリスクをなくすため、シェルの解析はデフォルトで無効です。信頼できるワークフロー向けに、明示的に有効化するモードも用意されています
• セキュリティレベルに応じたコマンドのホワイトリスト：
  • 安全：承認なしで実行できるコマンド
  • 承認が必要：実行前に明示的な承認が必要なコマンド
  • 禁止：明示的にブロックされるコマンド
• プラットフォーム固有のコマンドホワイトリスト
• 危険性のあるコマンドを対象とした、ノンブロッキングの承認ワークフロー
• ファイルベースのログを備えた包括的なロギングシステム
• 包括的なコマンド管理ツール
• 診断用のプラットフォーム情報ツール

インストール

オプション 1：Claude Desktop 拡張機能（.dxt）— 推奨

Claude Desktop へのワンクリックインストール：

1. 最新リリースから super-shell-mcp.dxt ファイルをダウンロードします

2. クイックインストール：Claude Desktop を開いた状態で .dxt ファイルをダブルクリックします

   または

   手動インストール：

   • Claude Desktop を開きます
   • Settings > Extensions に移動します
   • "Add Extension" をクリックします
   • ダウンロードした super-shell-mcp.dxt ファイルを選択します

3. 設定（任意）：必要に応じてカスタムシェルのパスを設定します

4. 使用開始 — 拡張機能はすぐに使用できます！

✅ DXT インストールのメリット：

• 開発者ツール（Node.js、Python など）は不要です
• 設定ファイルを手動で用意する必要はありません
• 依存関係を自動で管理します
• ワンクリックでインストールと更新ができます
• OS のキーチェーンに認証情報を安全に保存します

オプション 2：Smithery 経由でのインストール

Smithery 経由で Claude Desktop 用の Super Shell MCP サーバーを自動的にインストールするには：

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

オプション 3：手動インストール

# Clone the repository
git clone https://github.com/cfdude/super-shell-mcp.git
cd super-shell-mcp

# Install dependencies
npm install

# Build the project
npm run build

使い方

Claude Desktop 拡張機能（.dxt）のユーザー向け

.dxt 拡張機能（オプション 1）を使ってインストールした場合、すぐに使用できます！ 追加の設定は不要です。拡張機能がすべて自動で処理します：

• ✅ Claude Desktop の起動時に自動起動
• ✅ プラットフォームを検出し、適切なシェルを選択
• ✅ コマンドホワイトリストと承認ワークフローによる組み込みのセキュリティ
• ✅ Claude Desktop の拡張機能設定から任意で設定

手動インストールしたユーザー向け

手動でインストールした場合（オプション 2 または 3）、Claude Desktop または MCP クライアントを設定する必要があります：

サーバーの手動起動

npm start

または、直接実行します：

node build/index.js

MCP クライアントの手動設定

手動インストールの場合、Roo Code と Claude Desktop は、MCP サーバーに同様の設定形式を使用します：

NPX を使用する（手動設定に推奨）

Super Shell MCP を使う最も簡単な方法は NPX です。手動で設定しなくても、npm からパッケージを自動でインストールして実行できます。このパッケージは NPM の https://www.npmjs.com/package/super-shell-mcp で入手できます。

NPX を使用した Roo Code の設定

"super-shell": {
  "command": "npx",
  "args": [
    "-y",
    "super-shell-mcp"
  ],
  "alwaysAllow": [],
  "disabled": false
}

NPX を使用した Claude Desktop の設定

"super-shell": {
  "command": "npx",
  "args": [
    "-y",
    "super-shell-mcp"
  ],
  "alwaysAllow": false,
  "disabled": false
}

オプション 2：ローカルインストールを使用する

ローカルインストールを使用する場合は、以下を Roo Code の MCP 設定ファイル（~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json にあります）に追加してください。

"super-shell": {
  "command": "node",
  "args": [
    "/path/to/super-shell-mcp/build/index.js"
  ],
  "alwaysAllow": [],
  "disabled": false
}

コマンドラインフラグの代わりに環境変数を設定して、信頼できるシェルを指定し、シェル解析を有効にすることもできます。

"super-shell": {
  "command": "node",
  "args": [
    "/path/to/super-shell-mcp/build/index.js"
  ],
  "env": {
    "CUSTOM_SHELL": "/usr/bin/bash",
    "SUPER_SHELL_USE_SHELL": "true"
  },
  "alwaysAllow": [],
  "disabled": false
}

Windows 11 の例：

"super-shell": {
  "command": "C:\\Program Files\\nodejs\\node.exe",
  "args": [
    "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npx-cli.js",
    "-y",
    "super-shell-mcp",
    "C:\\Users\\username"
  ],
  "env": {
    "CUSTOM_SHELL": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
    "SUPER_SHELL_USE_SHELL": "true"
  },
  "alwaysAllow": [],
  "disabled": false
}

Claude Desktop の設定

以下を Claude Desktop の設定ファイル（~/Library/Application Support/Claude/claude_desktop_config.json にあります）に追加してください。

"super-shell": {
  "command": "node",
  "args": [
    "/path/to/super-shell-mcp/build/index.js"
  ],
  "alwaysAllow": false,
  "disabled": false
}

Windows ユーザーの場合、設定ファイルは通常 %APPDATA%\Claude\claude_desktop_config.json にあります。

プラットフォーム固有の設定

Windows

• デフォルトのシェル：cmd.exe（利用可能な場合は PowerShell）
• 設定パス：
  • Roo Code：%APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json
  • Claude Desktop：%APPDATA%\Claude\claude_desktop_config.json
• シェルパスの例：
  • cmd.exe：C:\\Windows\\System32\\cmd.exe
  • PowerShell：C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe
  • PowerShell Core：C:\\Program Files\\PowerShell\\7\\pwsh.exe

macOS

• デフォルトのシェル：/bin/zsh
• 設定パス：
  • Roo Code：~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
  • Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json
• シェルパスの例：
  • zsh：/bin/zsh
  • bash：/bin/bash
  • sh：/bin/sh

Linux

• デフォルトのシェル：/bin/bash（または $SHELL 環境変数）
• 設定パス：
  • Roo Code：~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
  • Claude Desktop：~/.config/Claude/claude_desktop_config.json
• シェルパスの例：
  • bash：/bin/bash
  • sh：/bin/sh
  • zsh：/usr/bin/zsh

シェル実行モードと環境変数

セキュリティ上の理由から、シェル解析はデフォルトで無効です。以下の環境変数を使って動作をカスタマイズできます。

• SUPER_SHELL_USE_SHELL：信頼できるワークフローでシェル解析を有効にするには、true（または 1/yes/on）に設定します。より安全なデフォルト設定を維持するには、省略するか false に設定します。
• CUSTOM_SHELL：シェル解析が有効な場合に使用するシェル実行ファイルの任意のパスです。
• SUPER_SHELL_COMMAND_TIMEOUT：デフォルトの 30s のコマンドタイムアウトを上書きする任意の値（ミリ秒）です。

⚠️ シェル解析を有効にすると、コマンドインジェクションのリスクが再び生じます。コマンドのソースとペイロードを完全に信頼できる場合にのみ有効にしてください。

/path/to/super-shell-mcp を、リポジトリをクローンした実際のパスに置き換えてください。

注：

• Roo Code の場合：セキュリティ上の理由から、alwaysAllow を空の配列 [] に設定することをおすすめします。これにより、コマンドを実行する前に承認を求めるようになります。確認なしで特定のコマンドを許可する場合は、たとえば "alwaysAllow": ["execute_command", "get_whitelist"] のように、そのコマンド名を配列に追加できます。
• Claude Desktop の場合：セキュリティ上の理由から、alwaysAllow を false に設定することをおすすめします。Claude Desktop では配列ではなくブール値を使用します。false はすべてのコマンドで承認が必要であることを意味し、true は確認なしですべてのコマンドが許可されることを意味します。

重要：alwaysAllow パラメーターを処理するのは MCP クライアント（Roo Code または Claude Desktop）であり、Super Shell MCP サーバー自体ではありません。クライアントがサーバーにリクエストを送信する前に承認プロセスを処理するため、サーバーはどちらの形式でも正しく動作します。

利用可能なツール

サーバーは以下の MCP ツールを公開します。

get_platform_info

現在のプラットフォームとシェルに関する情報を取得します。

{}

execute_command

現在のプラットフォームでシェルコマンドを実行します。

{
  "command": "ls",
  "args": ["-la"]
}

get_whitelist

許可リストに登録されたコマンドの一覧を取得します。

{}

add_to_whitelist

ホワイトリストにコマンドを追加します。

{
  "command": "python3",
  "securityLevel": "safe",
  "description": "Run Python 3 scripts"
}

update_security_level

ホワイトリストに登録されたコマンドのセキュリティレベルを更新します。

{
  "command": "python3",
  "securityLevel": "requires_approval"
}

remove_from_whitelist

ホワイトリストからコマンドを削除します。

{
  "command": "python3"
}

get_pending_commands

承認待ちのコマンド一覧を取得します。

{}

approve_command

承認待ちのコマンドを承認します。

{
  "commandId": "command-uuid-here"
}

deny_command

承認待ちのコマンドを拒否します。

{
  "commandId": "command-uuid-here",
  "reason": "This command is potentially dangerous"
}

デフォルトでホワイトリストに登録されるコマンド

サーバーにはプラットフォーム固有のコマンドのホワイトリストが含まれており、検出されたプラットフォームに基づいて自動的に選択されます。

安全な共通コマンド（すべてのプラットフォーム）

• echo - 標準出力にテキストを出力

Unix 系の安全なコマンド（macOS/Linux）

• ls - ディレクトリの内容を一覧表示
• pwd - 作業ディレクトリを出力
• echo - 標準出力にテキストを出力
• cat - ファイルを連結して出力
• grep - ファイル内のパターンを検索
• find - ディレクトリ階層内のファイルを検索
• cd - ディレクトリを変更
• head - ファイルの先頭部分を出力
• tail - ファイルの末尾部分を出力
• wc - 改行、単語、バイト数を出力

Windows 固有の安全なコマンド

• dir - ディレクトリの内容を一覧表示
• type - テキストファイルの内容を表示
• findstr - ファイル内の文字列を検索
• where - プログラムの場所を特定
• whoami - 現在のユーザーを表示
• hostname - コンピューター名を表示
• ver - オペレーティングシステムのバージョンを表示

承認が必要なコマンド

承認が必要な Windows コマンド

• copy - ファイルをコピー
• move - ファイルを移動
• mkdir - ディレクトリを作成
• rmdir - ディレクトリを削除
• rename - ファイル名を変更
• attrib - ファイル属性を変更

承認が必要な Unix コマンド

• mv - ファイルを移動（名前を変更）
• cp - ファイルとディレクトリをコピー
• mkdir - ディレクトリを作成
• touch - ファイルのタイムスタンプを変更、または空のファイルを作成
• chmod - ファイルモードビットを変更
• chown - ファイルの所有者とグループを変更

禁止されているコマンド

禁止されている Windows コマンド

• del - ファイルを削除
• erase - ファイルを削除
• format - ディスクをフォーマット
• runas - 別のユーザーとしてプログラムを実行

禁止されている Unix コマンド

• rm - ファイルまたはディレクトリを削除
• sudo - 別のユーザーとしてコマンドを実行

セキュリティに関する考慮事項

• すべてのコマンドは、MCP サーバーを実行しているユーザーの権限で実行されます
• 承認が必要なコマンドは、明示的に承認されるまでキューに保留されます
• 禁止されているコマンドは実行されません
• サーバーはシェルインジェクションを防ぐため、exec ではなく Node.js の execFile を使用します
• 引数が指定されている場合、許可されたパターンに照らして検証されます

ホワイトリストの拡張

add_to_whitelist ツールを使用して、ホワイトリストを拡張できます。例：

{
  "command": "npm",
  "securityLevel": "requires_approval",
  "description": "Node.js package manager"
}

NPM パッケージ情報

Super Shell MCP は、npm パッケージとして https://www.npmjs.com/package/super-shell-mcp で入手できます。

NPX を使用するメリット

NPX の方法（「設定」セクションのオプション 1 に記載）には、次のような利点があります。

1. 手動セットアップ不要：リポジトリのクローン、依存関係のインストール、プロジェクトのビルドが不要です
2. 自動更新：公開されている最新バージョンが常に使用されます
3. クロスプラットフォーム対応：Windows、macOS、Linux で同じように動作します
4. 設定の簡素化：絶対パスが不要になり、設定が短くなります
5. メンテナンスの軽減：管理や更新が必要なローカルファイルがありません

GitHub からの使用

GitHub の最新の開発バージョンを直接使用する場合：

"super-shell": {
  "command": "npx",
  "args": [
    "-y",
    "github:cfdude/super-shell-mcp"
  ],
  "alwaysAllow": [],  // For Roo Code
  "disabled": false
}

独自バージョンの公開

独自に変更したバージョンを npm に公開する場合：

1. package.json を詳細に合わせて更新します
2. "bin" フィールドが適切に設定されていることを確認します：

   "bin": {
     "super-shell-mcp": "./build/index.js"
   }
   

3. npm に公開します：

   npm publish
   

NPX のベストプラクティス

NPX を使用する MCP クライアントとの最適な統合のため、このプロジェクトでは以下のベストプラクティスに従っています。

1. 実行可能なエントリーポイント：メインファイルにはシバン行（#!/usr/bin/env node）が含まれており、ビルド時に実行可能になります。

2. パッケージの設定：

   • "type": "module" - ES Modules が使用されるようにします
   • "bin" フィールド - コマンド名をエントリーポイントに対応付けます
   • "files" フィールド - 公開時に含めるファイルを指定します
   • "prepare" スクリプト - インストール時にコンパイルが行われるようにします

3. TypeScript の設定：

   • "module": "NodeNext" - ES Modules を適切にサポートします
   • "moduleResolution": "NodeNext" - ES Modules との一貫性を保ちます

4. 自動インストールと実行：

   • MCP クライアントの設定では、パッケージを自動的にインストールして実行するために npx -y を使用します
   • プロセスはバックグラウンドで実行されるため、ターミナルウィンドウを占有しません

5. 公開プロセス：

   # Update version in package.json
   npm version patch  # or minor/major as appropriate
   
   # Build and publish
   npm publish
   

これらのプラクティスにより、別のターミナルウィンドウを必要とせずに、MCP クライアントが MCP サーバーを自動的に起動できるため、ユーザーエクスペリエンスと運用効率が向上します。

トラブルシューティング

クロスプラットフォームの問題

Windows 固有の問題

1. PowerShell スクリプトの実行ポリシー

   • 問題：PowerShell によってスクリプトの実行がブロックされ、「Execution of scripts is disabled on this system」というエラーが表示されることがあります
   • 解決策：PowerShell を管理者として実行し、Set-ExecutionPolicy RemoteSigned を実行するか、シェルの設定時に -ExecutionPolicy Bypass パラメーターを使用します

2. パス区切り文字

   • 問題：Windows のパスではバックスラッシュ（\）が使用されますが、JSON ではエスケープする必要があります
   • 解決策：JSON 設定ファイルでは、二重バックスラッシュ（\\）を使用します。例：C:\\Windows\\System32\\cmd.exe

3. コマンドが見つからない

   • 問題：Windows には ls や grep などの Unix コマンドがありません
   • 解決策：Windows の同等のコマンドを使用します（ls の代わりに dir、grep の代わりに findstr）

macOS/Linux 固有の問題

1. シェルの権限

   • 問題：コマンドの実行時にアクセスが拒否される
   • 解決策：chmod +x /path/to/shell を使用して、シェルに適切な権限が設定されていることを確認します

2. 環境変数

   • 問題：MCP サーバーで環境変数が利用できない
   • 解決策：シェルのプロファイルファイル（.zshrc、.bashrc など）で環境変数を設定します

一般的なトラブルシューティング

1. シェルの検出に関する問題

   • 問題：サーバーが正しいシェルを検出できない
   • 解決策：設定でシェルのパスを明示的に指定します

2. コマンド実行のタイムアウト

   • 問題：コマンドの実行に時間がかかりすぎてタイムアウトする
   • 解決策：コマンドサービスのコンストラクターでタイムアウト値を増やします

ロギングシステム

サーバーには、デバッグや監視を容易にするため、ログをファイルに書き込む包括的なロギングシステムが含まれています。

1. ログファイルの場所

   • デフォルト：サーバーのディレクトリ内の logs/super-shell-mcp.log
   • ログディレクトリは自動的に作成され、Git によって追跡されます（.gitkeep ファイルを使用）
   • ログファイル自体は .gitignore によって Git の対象外になります
   • サーバーの動作、コマンド実行、承認ワークフローに関する詳細情報が記録されます

2. ログレベル

   • INFO：一般的な動作情報
   • DEBUG：詳細なデバッグ情報
   • ERROR：エラー状態と例外

3. ログの確認

   • 標準的なファイル表示コマンドを使用してログを確認します。

     # ログ全体を表示
     cat logs/super-shell-mcp.log
     
     # ログの更新をリアルタイムで追跡
     tail -f logs/super-shell-mcp.log
     

4. ログの内容

   • サーバーの起動と設定
   • コマンド実行リクエストと結果
   • 承認ワークフローのイベント（保留中、承認、拒否）
   • エラー状態とトラブルシューティング情報

5. ホワイトリストの管理

   • 問題：カスタムコマンドをホワイトリストに追加する必要があります
   • 解決策：add_to_whitelist ツールを使用して、環境に合わせたコマンドを追加します

既知の問題

Android Studio Otter 2 Feature Drop との互換性

影響を受けるバージョン：Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 (Build #AI-252.25557.131.2522.14357309)

問題：Android Studio の MCP クライアント実装では、execute_command ツールの呼び出し時に配列パラメーターが文字列として誤ってシリアライズされます。そのため、引数を含むコマンドは次のエラーで失敗します。

Error: Expected array, received string

例：

// This fails in Android Studio Otter 2
execute_command(
  command = "git",
  args = ["add", "."]  // Sent as string '["add", "."]' instead of array
)

根本原因：これは Android Studio の MCP クライアントのバグであり、super-shell-mcp の問題ではありません。サーバーではスキーマ内で args が正しく array 型として定義されており、次のクライアントでは正常に動作することが確認されています。

• Claude Desktop
• 公式 MCP SDK クライアント
• その他の MCP 互換ツール

ステータス：これは Android Studio のバグです。super-shell-mcp サーバーは MCP 仕様を正しく実装しています。

回避策：現在、利用できる回避策はありません。この問題が発生したユーザーは、Android Studio／JetBrains チームに報告してください。

参考情報：

• 報告された問題：#20
• 関連ドキュメント：Android Studio Gemini MCP Integration

ライセンス

この MCP サーバーは MIT License の下でライセンスされています。つまり、MIT License の利用規約に従う限り、ソフトウェアを自由に使用、変更、配布できます。詳細については、プロジェクトリポジトリの LICENSE ファイルを参照してください。