Mac Shell MCP Server

Mac Shell MCP Server

AI クライアントが、指定したディレクトリ内に限定して、少数の固定された読み取り専用シェルコマンドを実行できるようにする MCP サーバーです。

その根底にある考え方は一つです。エージェントは自分自身の権限を拡大できません。 ポリシーを編集するツールも、エージェントが処理できる承認キューもなく、引数を解釈するシェルもありません。

1.x からアップグレードする場合 2.0.0 は破壊的変更を含みます。7 つのツールが削除され、認可モデルが置き換えられました。1.x からの移行をご覧ください。1.x には、4 人の独立した研究者から報告された 2 件の脆弱性が含まれていました。セキュリティ勧告をご覧ください。

機能

ツール	用途
execute_command	設定したディレクトリ内で許可されたコマンドを実行します
execute_external_command	ディレクトリの外でコマンドを実行します — 人間に確認できるクライアントが必要です
execute_pipeline	シェルを使わず、読み取り専用コマンドを標準出力から標準入力へ連結します
get_policy	推測して拒否されるのではなく、何が許可されているかを確認します
suggest_policy_config	観測された使用状況を、あなたが適用する設定に変換します

デフォルトのコマンド

ls pwd echo cat head tail wc grep

それぞれのコマンドで使用できるフラグは許可リストに限定されています。どのコマンドもファイルへの書き込み、別のプログラムの実行、環境からの設定の読み取りはできません。

find、git、rm、およびすべてのインタープリターはデフォルトでは含まれていません。 追加することはできますが、含まれていない理由を把握しておく必要があります。

• find -fprintf は攻撃者が指定した内容を、攻撃者が指定したパスに書き込めます。一方、find は自然に読み取り専用として分類されます
• git はリポジトリ自身の .git/config にあるコマンドを実行します。それを無効にする環境変数はありません
• インタープリター（python、perl、awk、node、osascript、…）は、インラインコードを引数として受け取ります

インストール

npm install -g @the_cfdude/mac-shell-mcp

次に、ポリシーを作成します。

mkdir -p ~/.mac-shell-mcp
cp .mac-shell-mcp.sample.json ~/.mac-shell-mcp/config.json
$EDITOR ~/.mac-shell-mcp/config.json    # set allowedRoots to your project
chmod 444 ~/.mac-shell-mcp/config.json  # defence in depth; see Security

MCP クライアントに追加します。

{
  "mcpServers": {
    "mac-shell": { "command": "npx", "args": ["-y", "@the_cfdude/mac-shell-mcp"] }
  }
}

ルートを設定せずに新規インストールすると、すべての操作が拒否されます — これは意図された動作です。拒否メッセージには、許可されたコマンドと設定ファイルの場所が示されるため、最初の失敗で次に何をすべきかが分かります。

設定

ポリシーは次の順で検索され、最初に一致したものが使用されます。統合は行われません。

1. $MAC_SHELL_MCP_CONFIG — 明示的に指定されたパス
2. ~/.mac-shell-mcp/config.json
3. ホスト環境（MAC_SHELL_ROOTS、MAC_SHELL_COMMANDS）
4. 組み込みのデフォルト

作業ディレクトリからポリシーが読み込まれることはありません。 クローンしたリポジトリが、そのリポジトリを開くエージェントを管理するポリシーを提供できてはなりません。

{
  "allowedRoots": ["/Users/you/Projects/my-project"],
  "programDirectories": ["/usr/bin", "/bin", "/usr/sbin", "/sbin"],
  "commands": {
    "grep": {
      "program": "/usr/bin/grep",
      "effect": "read",
      "allowedArgs": ["-i", "-n", "-r", "-l", "-E", "-F"],
      "permission": "allow",
    },
  },
}

permission には allow、ask、deny を指定します。ask には MCP の elicitation を提供するクライアントが必要です — 人間に確認できることを意味する唯一の機能です。この機能がない場合、ask は allow ではなく、常に deny になります。

判定方法

認可は、呼び出しごとに effect × scope で計算されます。 プロジェクト内での grep は許可されますが、同じ grep でも ~/.aws に対して実行する場合は許可されません。コマンド名だけで判断されることはありません。

• シェルは使いません。 execFile に shell オプションが渡されることはないため、引数は解釈されずに OS に渡されます。;、$()、バッククォートが評価されることはありません。そのため、スペース、かっこ、角かっこを含むファイル名も通常どおり動作します。
• 引数だけでなく、プログラムも認可されます。 コマンドはプログラムディレクトリから絶対パスに解決され、ベース名ではなく解決されたパスで照合されます。また、ルート内に解決される場合は拒否されます。ルートにはデータを置き、コードは置きません。
• 環境は継承されず、構築されます。 そのため、RIPGREP_CONFIG_PATH のような変数を使って、引数リストに現れないヘルパープログラムを紛れ込ませることはできません。
• 許可リストを使い、拒否リストは使いません。 拒否リストには、誰かが思いついたフラグしか載りません。
• スコープには作業ディレクトリが含まれます。 そのため、パス引数のないコマンドは、何も指定していないために許可されるのではなく、実行される場所によって判断されます。

セキュリティ

ポリシーファイル、その親ディレクトリ、プログラムディレクトリ、および監査ログのディレクトリ全体は、保護対象の場所です。デフォルトのコマンドセットには書き込みを行うものが含まれていないため、初期状態ではどのコマンドからもアクセスできません。書き込みを行うコマンド（名前で判定される cp、mv、rm、tee、ln、chmod など）を追加した場合、パス引数が保護対象の場所を指す呼び出しは拒否されます。パスによる照合に加えて、ファイルシステム上の同一性でも照合されます。このチェックはコマンド名に基づいており、任意のプログラムが行う処理を判定するものではありません。このリストにない書き込みコマンドは対象外のため、書き込み先を信頼できる場合に限って追加してください。

追加の独立した防御策として、設定ファイルに chmod 444 を設定するとよいでしょう。これは保護の仕組みそのものではありません。ファイルの置き換えに必要なのは、ファイルへの書き込み権限ではなく、その ディレクトリ への書き込み権限だからです。

許可されたリクエストも拒否されたリクエストも、すべて追記専用の監査ログに記録されます。

既知の制限事項を明記します。詳細は SECURITY.md を参照してください。

• パスの検出はヒューリスティックであり、検出に失敗した場合は安全側に倒して拒否します
• ルート内のすべての内容は、再帰検索を 1 回実行するだけで自由に読み取れます
• ask の強度は、ホスト側の承認プロンプト次第です
• 同じコマンド名でも、実装によってフラグの意味が異なります

脆弱性の報告は、非公開のアドバイザリ または [email protected] までお寄せください。

1.x からの移行

削除済み： add_to_whitelist、update_security_level、remove_from_whitelist、approve_command、deny_command、get_pending_commands、get_whitelist。

最初の 3 つは、どのクライアントでも禁止されたコマンドを safe に昇格できる機能でした。次の 3 つは、リクエスト元のエージェントが単独で処理しきれる承認ワークフローを構成していました。get_whitelist は get_policy に置き換えられました。

実行時に変更していた許可リストは、編集する設定ファイルに置き換わり、サーバーは起動時にそのファイルを読み込みます。1.x で FORBIDDEN だった rm は引き続き利用できないため、以前動作していたものが動作しなくなることはありません。

開発

npm install && npm run build
npm test          # run it twice; a suite that only passes once is not passing
npm run lint && npm run format:check

設計と仕様：openspec/changes/mac-shell-mcp-2-security-redesign/。

ライセンス

MIT — LICENSE を参照してください。